Call API action

Avatar

By Alina Panaite

updated about 2 months ago

The Call API action enables you to perform REST/HTTP requests to a specified web API to query data from apps and services. You can retrieve, add, delete and update data. 

PROCESIO integrates Call API action with your API authentication credentials defined in Credentials Manager. This means that you have to create an API credentials configuration for the web service/app you want to connect to in Credentials Manager (check Working with Credentials Manager).

For example, if you want to connect to a JIRA REST API web service, you must once configure the authentication credentials of JIRA service in Credentials Manager and you can use this configuration in setting up Call API actions.

You can test the request and see the response received from the API server that helps you troubleshoot if needed.

How to configure the Call API action?

Go to the Process Designers section and open a new or an existing process. Actions configuration can be performed once they are dragged and dropped on canvas. 

Step 1: Drag the Call API action from Toolbar and drop it on canvas; click on the action to open the Properties Panel;

Step 2: You can edit the action name;

Step 3: Select first the API credentials configuration in Properties Panel. The API  credentials configuration needs to be created upfront in Credentials Manager to be displayed in the list.  

 If the API configuration you need is not created upfront, you have a shortcut in the selector to proceed to the Credentials Manager page.

Step 4: Click on Call API (not configured) card to go to the configurations steps.

Step 5: Call API configuration - the Request builder

 

  1. Request Method: in this dropdown list you will find several methods that can be used to send different types of requests.

  2. URL: in this field, the URL to request is already populated with details from the API credentials configuration selected at Step 1; you need to add the Method Name and IDs between "{ }" to complete your request URL/endpoint. Any information provided in the Query Params tab will be added in the URL.

  3. Tabs:

    • Query Params: this tab is used to specify any HTTP query parameters you may want to include with your request. A new line is added once the previous one is filled in. Query Params will be appended to the end of the request URL, following "?". You will not be allowed to add query params directly in the URL. To send a path parameter, enter the parameter name into the URL field, after a colon ":".

      The Query Params table:

      • Name: the name of the parameter;
      • Value: the value of the parameter (can be a process variable as well);
    • Headers: this tab is used to specify any optional HTTP request headers you may want to include with your request. A new line is added once the previous one is filled in. 

      The Headers table:

      • Name: the name of the header;
      • Value: the value of the header (can be a process variable as well);
    • Body: allows you to specify the data you need to send with the request; the editor supports the JSON format.

Request can contain process variables in Query Params, Headers, Body. For using process variables, press # key, which will display the variables selector. All process variables used in Call API configuration will be displayed by default in Test Action > Test Values section.  


 Depending on Authorization type defined in the selected API credentials configuration, API key and their values may be added in Headers or Query Params tabs to be passed along with the request. 

Output Variables

In order to make use of the data that will be received in the Response further in the process flow, you need to map the outputs to process variables. There are 3 types of possible output that you can map:

  • Status Output: stores the status code received from HTTP request, as a string or JSON variable.
  • Body Output: stores the response received from the HTTP request, as an integer process variable.
  • File Output: stores the file received from from the HTTP request, a file type process variable.

Test the Call API Action

Once the Request builder is configured, you can Test the action. Click on "Test Action" on the bar and a new section dedicated to testing will open.  

Test Values: in this table you will populated under "Variables" all the process variables used in the configuration of the Request. The "Type" of the process variable is also displayed, this helping you to assigned the correct test values to variables. Hit "Test Action" to test the configuration.

Consider that sending a test request with DELETE,PUT,UPDATE method may alter the data. 

                               

Test Output: will display the Status of the test in Test Status (if it passed or failed) and also the response outputs. 

If the returned Test Status is "Successful"  but HTTP status code (Status Output) is 400/500 (meaning that the server did not return an actual response for some reason), this usually means that the action configuration passed the test. However, it may be the server that encountered an unexpected condition that prevented it from fulfilling the request.

An API response consists of status code, body and files. 

Status output: status code received from server.

Body Output: once the response has been returned in body, you can Download or Save to clipboard.

File Output: if the response returns a file, you can see the name of Download it.


Related links

Working with Process Variables

Working with Data Types

Working with Credentials Manager



Did this answer your question?