External API Requests

External API Requests allow you to define request templates and then trigger outgoing calls to any API from within business processes. With them, you can connect your project to any third-party service, even if no module exists for it yet in the marketplace.

Definition

Consult the specifications of how the request should be structured in the API documentation of the service provider you want to connect with.

1. To define a new request template, go to the "Business Logic" tab on the sidebar (1), switch to the "External API Requests" tab (2), and click "New API Request" (3).

2. Give the new request a name and, optionally, a description.

3. Select the request HTTP method and its URL.

4. Define URL parameters, query parameters (only for GET requests), headers, and the body of the request by inputting the parameter name (1), its type (2), and clicking "Add Param" (3).

The actual value of these parameters will be defined at the time of the execution of the business process, where the request is triggered.

To understand the difference between URL and query parameters, read more here. Regardless of the standards though, the API documentation of the service provider you want to connect with is the best source of information on how to build up the request.

You can also autofill the request headers and body by inputting sample JSON, the system will create all the necessary parameters automatically.

You don't have to add new parameters on every tab. Some requests may not contain any URL parameters, headers, or body at all, for example.

In case that your request contains objects (e.g. car -> color, size, etc.), you will have to create virtual models to process these objects later in your business processes. Do so by selecting "Model" in the parameter type selector, and introducing the child elements that you would need. You can nest the objects as many times as you need (i.e. object within object) and create virtual model arrays. In case that you have used the autofill, this process was completed automatically.

5. Change the request's settings, such as SSL verification, timeout, and error handling in the "Settings" tab.

6. Test out the request by clicking "Test Request" and inputting all the required parameters. Check the response from the server and autofill the response headers and body automatically, or do so manually.

7. Save the request template by clicking "Save Request".

Use

After you define and save a new request, a new block will become available in the Business Process Editor to trigger it.

 You will have to provide it with all the components that you would like to add to the request (URL and query parameters, headers, and the body) as data models, which can be made using these blocks. In the output, you will be able to extract the formatted body of the response, its headers, and response status. You can expand these models using these blocks.

You don't have to connect all the data inputs for the request to trigger correctly. For example, if you have a request with no URL parameters, you don't have to create its model and connect it.

For every virtual model that you have defined, 2 new blocks will be added to your Business Process Editor to make and expand it.

Monitoring

Every time you trigger an API request, the system will output to the logs its type and address, the request body, the response HTTP status code, and the response body. You can output other info, such as specific fields of the response body, or the latency to logs using the Write to Log block.