API Call

The API Call node is a powerful tool that enables you to make requests to any available API. This node provides a flexible and efficient way to interact with external systems and integrate them into your workflows (see Picture 1).

Picture 1. API Call node task flow

With the API Call node, you can easily connect to a wide range of APIs, such as social media platforms (LinkedIn, Facebook, Twitter, Google, etc.), banking services (Visa, Mastercard payment and info services), web services, and exchange data with them.

Before getting started with writing API requests, it is crucial to thoroughly read the documentation of the specific API you intend to use. This will help you understand the required structure and authentication methods for making successful requests. It will also provide you with crucial information, such as the API endpoints, request methods, parameter formats, etc.

Node Settings

API request URL

URL - Request URL/endpoint. Corezoid supports the standard HTTP/HTTPS protocol and can accept any valid endpoint format, including URLs, IP addresses, and more.

Request format:

Default - standard HTTP/HTTPS request format. It adds a convenient Key-Value editor for query parameters and a request method dropdown menu.

Corezoid - similar to the Default format, but removes the ability to select a request method.

Raw - free form request format. Allows you to write custom request bodies. It is useful in cases when an API follows a non-standard request format.

Request method

Allows you to specify the type of request you want to make using a dropdown menu. It's important to note that some APIs may have the same endpoint for different request methods.

POST - send data
GET - retrieve data
PUT - create or update existing data
DELETE - delete data
HEAD - similar to POST, but does not return a response body
PATCH - update only a part of the data

Data format

• JSON
• form
• XML

Content-Type

Content-Type is used to indicate the format of the data being sent in the request body. This field will be pre-filled automatically based on the Data format you've selected, however, you can edit it to fit your specific needs.

Default types based on Data format:

• JSON - application/json; charset=utf-8
• form - application/x-www-form-urlencoded; charset=utf-8
• XML - application/xml; charset=utf-8

Request Parameters

Request's query parameters.

Key-Value

Key - parameter name.
Value - parameter value.

Add "key-value" - add a new parameter field.

Code editor - code editor of the corresponding JSON.

Other

Header parameters - request’s Header parameters. Headers are used to provide additional information about the request, such as authentication parameters, and various metadata. You can specify it in the same Key-Value format as the Request Parameters.

Customize response parameters - allows you to modify the response header and body parameters. It also allows you to specify the response format before the task is released from the node.

This feature can be particularly useful when dealing with APIs that provide an incorrect response format or do not specify a format at all. By customizing the response parameters, you can ensure that the response is parsed correctly.

Another use case for this feature is to minimize the amount of data to be added to a task. Oftentimes, your API request will return a lot of data, but you only need to extract a small number of specific parameters. In this case, you can use the Customize response parameters feature to only extract the necessary data.

Limit the number of simultaneous requests to the API - This feature allows you to control the maximum number of concurrent requests made to the API. By default, it is set to 5, but you can adjust it to comply with the number required by the API.

Add system parameters to the request- This checkbox allows you to add Corezoid's system parameters to your API request. These parameters are necessary when you are making a request to Corezoid's API. The parameters that will be added are conv_signature, conv_time, and conv_id. You can learn more about them here.

Sign the request with secret key - This option is specifically designed for making requests to Corezoid's API, which requires all requests to be authenticated with a secret key. You must also select the "Add system parameters to the request" option to include the necessary system parameters along with the request.

RFC standard response - When this option is selected, the response will be processed in compliance with the RFC standard.

When this option is selected, a response body is mandatory for response codes 200 and 201. For the 202 response code, the response body is optional.

Include debug info - Enabling this option adds extra information about the API request to a task parameter called conveyor_api_debug. This additional information includes the execution time, request body size, response code, and response body size.

Sample conveyor_api_debug object:

 "__conveyor_api_debug__": {
        "http_exec_time": 328.552,
        "http_req_body_size": 0,
        "http_res_code": 200,
        "http_res_body_size": 1132
    }

Sign the request by certificate - In certain cases, APIs may require you to include a client certificate with your request. If your API mandates the use of a client certificate, you can conveniently add it by selecting this option.

The client certificate should be in PEM format. It should be formatted like this:

-----BEGIN RSA PRIVATE KEY-----
....your private key goes here....
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
....your certificate goes here....
-----END CERTIFICATE-----

Alert if the number of tasks in the node queue reaches the following number - a condition that will be met when the node has a specified number of tasks in it. If this option is selected, a new edge will be created.

Maximum interval, for which the task stays in the node before being forwarded - the amount of time a task must spend in this node. Can be specified in seconds, minutes, hours, or days.

Examples

There are innumerable ways in which companies choose to implement their APIs. They can use different data formats, however, JSON and XML are the most commonly used. Some require headers, some don't. Some require a certificate, others don't. Some make you generate an authentication code and periodically renew your access token, while others simply want you to provide an API key or token.

All of these choices have good reasons behind them, and Corezoid strives to simplify the process of working with all the different API configurations, but it means that every case is a little bit different and will require you to look up the specific requirements of the API you are using. This also means that there is no obvious set of examples that would cover all possible features.

In this section, we provide an illustration of making an API call to one of the more popular libraries. For more intricate examples, we recommend exploring the tutorials section, where you can find guidance on handling more complex scenarios and configurations.

API call to OpenWeatherMap

OpenWeatherMap is a popular API that you can use to check the weather at any location. It is also free!

For the purpose of this example, let's say we want to get the current weather in San Fransico.

A good place to start is to look at the API documentation. When doing so, you want to find the answers to the following questions:

• What is the endpoint URL?
• What parameters need to be specified? Where?
• How does this API handle authorization/ authentication?

In the API's documentation, we find the structure of the API call:

https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key}

Here, https://api.openweathermap.org/data/2.5/weather is the endpoint, and lat, lon, and appid are the parameters.

We are told that appid is our unique API key, which we get can by creating an account with the service. You can get yours for free here. The API key is what this service uses to authorize requests. Once you make an account, you will need to generate a new API key. Store it somewhere safe!

Now that we have all the required information, we can fill out our API Call node and make our first request (see Picture 2).

Picture 2. Making a request with specified parameters from the API Call node

Note that in the URL field, we only include the endpoint URL, and add the parameters under Request Parameters. This is done for convenience only, as separating the two makes it easier to see and manipulate parameter values. You can still specify the parameters within the URL string if you wish to do so.

Another thing to note is that we changed the Request method to GET since we will be getting information from the resource.

Now, we switch to View mode and create a new task with no parameters, since our process doesn't take any.

The task passes through the API Call node, and we instantly get back a response with the current weather in San Francisco (see Picture 3).

Picture 3. A response from an API triggered by a task sent through the API Call node

Looks like it's cloudy. Better grab a sweater!

Error handling & troubleshooting

When an error occurs in the node, a task goes to the auxiliary Condition output node (Picture 4):

Picture 4. API Call node's auxiliary output node

This auxiliary Condition node is used for storing error parameters. With that, the following fields are added to the initial task depending on the error and node type: