API Call

Overview

The API Call node is a powerful tool that enables you to make requests to any available API. The node provides a flexible and efficient way to interact with external systems and integrate them into your workflows. With the API Call node, you can easily connect and exchange data with a wide range of APIs, such as:

• Social media platforms (LinkedIn, Facebook, Twitter, Google, and so on)
• Banking services (Visa and Mastercard payments and info services)
• Web services

Settings

The API Call node has the following parameters:

1. (Optional) Title and Description: Name and details of the node.

2. API request URL:

   • URL: Indicates the URL/endpoint request.
     Note: Corezoid supports the standard HTTP/HTTPS protocol and can accept any valid endpoint format, including URLs, IP addresses, and more.

   • Request format:

     • Default: A standard HTTP/HTTPS request format that adds a convenient Key-Value editor for query parameters and a request method dropdown menu.
     • Corezoid: Is similar to the Default format, but it removes the ability to select a request method.
     • Raw: Is a free-form request format that allows you to write custom request bodies and is used in cases when an API follows a non-standard request format.

   • Request method: Specifies the type of request you want to make:

     • 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
       Note: Some APIs may have the same endpoint for different request methods.

   • Data format: JSON, XML, Form

   • Content-Type: Indicates the format of the data being sent in the request body.
     Default types based on the data format:

     • JSON: application/json; charset=utf-8
     • XML: application/xml; charset=utf-8
     • Form: application/x-www-form-urlencoded; charset=utf-8
       Note: The field is filled out automatically based on the data format that you have selected. You can edit it if needed.

3. Request parameters: Request’s query parameters:

   • Key: Key to specify variables; use a unique name. When updating existing variables, use their original names as a key.
   • Value: The value you want to assign to the corresponding Key parameter. The value can be a constant, a variable reference, or a function applied to a variable.

   Note: For more information, go to Parameters and functions.

   • Type of data:
     • String (S)
     • Number (N)
     • Boolean (B)
     • Array (A)
     • Object (O)

   Note: For more information, go to Data types.

   • Code editor: Shows the JSON format of the entered key and value. You can write and include additional code, which will be executed when a task enters the node.

4. Other:

   • Header parameters: Indicates request’s Header parameters that 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 Request Parameters.

   • Customize response parameters: Modifies the response header and body parameters and specifies the response format before the task is released from the node. The feature can be used when:

     • 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.
     • Minimizing the amount of data to be added to a task. Sometimes an API request returns a lot of data, but only a small number of specific parameters need to be retrieved. In this case, you can use the Customize response parameters feature to extract only the needed data.

     Note: To add a key and a value, see step 3 of this topic.

   • Limit the number of simultaneous requests to the API: Controls 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: Adds Corezoid system parameters to the API request that are required to make a request to the Corezoid API and can be the following: conv_signature, conv_time, and conv_id. For more information, go to Corezoid API.

     Some APIs have strict requirements for the parameters that can be included in a request. If this is the case for the API you are using, you may need to clear the checkbox to exclude Corezoid system parameters from your request.

   • Sign the request with the secret key: Makes requests to Corezoid's API, which requires all requests to be authenticated with a secret key.
     Note: To include the necessary system parameters along with the request, you have to select the Add system parameters to the request option.

   • RFC standard response: With this option selected, the response will be processed in compliance with the RFC standard.
     Note: When this option is selected, the response body is mandatory for response codes 200 and 201 and is optional for the 202 response code.

   • Include debug info: Adds extra information about the API request to a task parameter called conveyor_api_debug that includes execution time, request body size, response code, and response body size.

     "__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: If APIs require you to include a client certificate with your request, you can add it in the PEM format by selecting this option.

     -----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: Helps monitor whether the number of tasks in the node exceeds the specified threshold. When selecting the checkbox, you have to enter the needed number of tasks in the field that appears below.

   • Maximum interval, for which the task stays in the node before being forwarded: The amount of time a task is allowed to be in the node; can be set in seconds, minutes, hours, and days.
     Note: The checkbox has a minimum value of 30 seconds. You can set a shorter interval by using the Unixtime function.

   

Examples

There are innumerable ways in which companies choose to implement their APIs:

• Using different data formats, including JSON and XML as the most popular ones
• Applying certificates
• Getting an API key or token
• Generating an authentication code and periodically renewing their access token

API call to OpenWeatherMap
OpenWeatherMap is a popular free API that you can use to check the weather at any location.
To check the weather in San Francisco:

1. Create a Process and add the API Call node.
   Note: For more information, go to Create Process and Add node.

2. Go to OpenWeatherMap and get the needed API where:

   • https://api.openweathermap.org/data/2.5/weather is the endpoint URL.
   • lat, lon, and appid are parameters.
   The appid parameter is a unique API key that you get by creating an account with the service.

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

3. In API request URL of the API Call node details panel:

   1. In the URL field, enter the endpoint URL.
   2. In the Request method dropdown list, select GET.

4. In Request parameters of the API Call node details panel, enter the lat, lon, and appid parameter values.

5. Switch to the View mode by clicking View on the upper panel.
6. In the New Task dialog that opens, click Add task.
   

On the task details form, you can see that it’s cloudy in San Francisco now.

Error handling & troubleshooting

When an error occurs in the API Call node, a task goes to the auxiliary Condition output node that is used for storing error parameters.

When an error occurs during the task processing, you may see the following error parameter names in the task.