Creating custom HTTP operations on API flows

When you create a flow for an API, you can define custom operations on a resource (model) that are suitable for your business needs.

There are various options for you to create custom operations.

  • You can choose from six different verbs for your custom API: GET, PUT, POST, PATCH, DELETE, and HEAD.
  • By selecting the Use model_name ID check box, you can create instance APIs on the resource.
  • You can customize the request and response model for your API by selecting from the predefined model on the API.
  • You can set a unique operation name (relative path) for your API.
  • There are optional query parameters that are part of the URL parameters.
  • You can provide a description for your custom operation, which can be viewed in the Swagger definition.
Figure 1. Custom operations definition editor
Sample input in the custom operations definition editor

Let's work through a simple use case, which demonstrates how you can use the custom API features.

Scenario

We want to provision an API that allows the API consumer to declare an opportunity in Salesforce as closed and add the name of the 'closer' as a comment. Note that this use case interacts with Salesforce only.

Procedure

  1. We first create an API with two models – Opportunity and Account – then define the properties that make up the model. We then define a custom operation on the Opportunity model. For this example, the operation is to close an opportunity if the ID of the opportunity is known. We set the following properties:

    • Set HTTP Verb to POST
    • Set Operation name to /close (the complete path would be /opportunity/:id/close)
    • Select Unique Opportunity ID
    • Body Parameters:
      Input
      Specify the name and contact details of the person who's authorizing the closure (Account model)
      Output
      Specify the full details of the closed opportunity (Opportunity model)
  2. The next step is to implement the flow and do any necessary mapping, where we add any necessary actions or logic to achieve the expected behaviour. For example, a simple flow might use the Salesforce Replace or create opportunity action to update the opportunity that's identified by the ID, and include the account and name of the closer from the incoming payload in comments.
    Figure 2. Custom operations definition – Closing opportunity
    Sample entries for a custom operations definition
  3. The final step is to download the Swagger from the Manage tab and invoke the API.
    Figure 3. Swagger for the Closing opportunity API
    Sample Swagger for the Closing opportunity API

Some additional points to consider

  • You can now define up to 10 models in an API.
  • You can start an API only if at least one of its models has a complete implementation of an operation.