Learn how to configure API requests in Actioner
An API request works by requesting information from a server and then receiving a response for it. Considering the soaring popularity of APIs, many tools are offering API as a service. Actioner is an environment where you can send API requests to your apps, get responses from them and use them to design your actions.
Building API requests
You can send API requests to perform actions in your applications. Adding a checklist to a Trello card or creating a new Jira task are some example actions that can be performed with Actioner API requests.
You can also send API requests to retrieve data from your applications and use them as the dynamic datasources for your input and output components. While adding a new deal, you can get your company list from HubSpot. While listing your users, you can display their names instead of their user ids.
API requests can retrieve, add, update, and delete data in your app. Whether you are building actions for your users or testing your own, you can try out requests in Actioner. Your requests can send parameters, authorization headers, and any raw body data your app requires.
Configure API requests
Your app's REST API might expect various detail. You can select a connection to send an API request, configure the endpoint, params, header and body of your request in Requests tab.
1. Connection of the request
Select a connection for your request from available options.
Once you have a connection added to your app, you can use it for building your requests. Connections make it easy to send API requests without the need to configure base URLs or authentication details each time you create a new request.
Available connections that you can select for your API requests are the ones added to your app. To add a new connection, go to your app's App settings tab and click + Add connection to create a new connection.
Actioner provides preset connections with the most popular apps. It is also possible to create custom connections with generic basic authentication and generic API key options.
To learn more about connections in Actioner, visit this page. If you are looking for a preset connection with your tool, contact us.
When a connection is selected, the base URL of the connection is copied as a base URL to your request. This URL is not editable inside the request, you need to update it by navigating to that connection in App settings tab. Once the connection URL is updated, the base URL in your request is updated accordingly.
Selecting a connection for your request is not mandatory. You can proceed to send requests by providing full URLs and setup authorization details such as API key or login credentials in the request param, headers and body fields. However, sending requests with connections is highly recommended.
There are three important benefits of selecting a connection for your request:
- You can re-use the connection's base URL and authentication credentials for any request in your app. This saves you time with not having to enter the same URL or authentication parameters for each request.
- Connections can be setup with selected sharing scopes. When Shared credentials option is disabled for a connection, each user will need to enter their username/password, API keys or access tokens to execute actions using that connection.
- Uses for different authentication types:
- OAuth2 authentication: Actioner supports OAuth2 connection with GitHub, Jira, Zendesk, and other popular apps. It is not possible to configure OAuth2 by setting up a request. If you are connecting with GitHub, Jira or other apps we provide OAuth2 option, go to Connections page of your app and add a new connection.
- API Key authentication: To authenticate with an API key in your app, you need to provide a secret private API key in the HTTP headers or URL params. Setting up an API key in the request exposes the API key on request configuration -- meaning that the API key becomes visible to all app admins.
- Other HTTP authentications such as Basic or Bearer: Similar to API key, you need to provide your login credentials in the HTTP headers or URL params while configuring a Basic or Bearer authentication. This exposes your login credentials on request configuration. The credentials become visible to all app admins.
2. API request method
By default GET method is selected when a new request is added. You can select from available request methods:
- GET: typically used to retrieve data
- POST: typically used to add new data
- PUT: typically used to replace existing data
- PATCH: typically used to update some existing data fields
- DELETE: typically used to delete existing data
- HEAD: typically used to get HTTP header, but without body
- OPTIONS: typically used to get allowed methods for a resource
3. API request URL and endpoint
Each request requires a URL representing the API endpoint you are sending the request to and each operation performed on an API is typically associated with an endpoint. By default, the base URL is copied from your connection URL if a connection is selected for your request. When you enter an endpoint in request configuration, it is added as a suffix to the connection's base URL.
Assume that you've a Zendesk connection added to your app and you are looking to list your users in Zendesk. Your Zendesk connection's base URL is
https://acme.zendesk.com is the base URL of the connection. By adding
/api/v2/users on the request endpoint field, the request's URL becomes
https://acme.zendesk.com/api/v2/users. The API request is sent to this URL.
If you are not sure how to enter URLs, check in with your app's API, for e.g. within their developer documentation.
If your request requires path parameters, enter them on the request URL. You can optionally add query parameters to the URL, or can enter them in the Params tab.
You can setup query parameters on Params tab. To add a query parameter, click + Add new parameter and enter the parameter as a key, value pair.
If your request doesn't require a Body or Headers, go ahead and click the green Run button to see its response. Otherwise, continue with configuring Headers and Body of your request.
Some APIs require you to send particular HTTP headers in your requests, typically to provide additional metadata about the operation you are performing. These can be set up in Headers tab. key, value pairs added here are appended to your request's headers.
6. Request body
You will need to send the data in request Body whenever you need to add or update structured data. For example, if you're sending a request to add a new customer to a database, you might include the customer details in JSON. Typically you will use body data with POST, PUT, and PATCH requests.
Body tab in API requests allows you to specify the data you need to send with a request. You can send various types of body data that works with your app's API.
If you are configuring a body for your API request, make sure that you setup the correct headers that indicate the content type your API would require to process data correctly.
For form data and form URL encoded body types, Actioner automatically attaches the correct Content-Type header. If you select Raw option to enter a request Body, Actioner sets the Content-Type header based on the selected content type, such as APPLICATION/JSON or TEXT_PLAIN.
Supported body types:
Form-data: Website forms often send data to APIs as
multipart/form-data. You can replicate this in Actioner entering form fields on Form-data tab.
Form URL encoded: URL-encoded data uses the same encoding as URL parameters. If your app's API requires URL-encoded data, add the relative form fields on the Form URL encoded tab.
There is sometimes confusion between form
URL-encoded. If you are unsure which one you need, check with your API provider.
Raw: You can use raw body data to send anything you can enter as text. You can select from below options:
Depending on the status code of the response, you can setup your API requests to be retried up to 10 times by putting a delay in between retry attempts. This allows you to monitor the errors returned for your API requests, whether user created or system generated, so that they can be caught and handled.
- if request returns a response code other than the selected ones.
- else if max number of attempts are reached.
To set a retry logic for your API request,
- Go to Settings tab of your request
- Enable Retry option.
- Select a status code or multiple. By default, 429 and 503 are selected since they are the most common errors that need a retry mechanism implementation. You can select from successful or unsuccesful codes from the list. List includes all 2xx, 3xx, 4xx, 5xx and 6xx responses. You can add max 10 error codes.
- Select max number of retries. You can select to retry sending the API request up to 10 times. Once the Actioner gets a response with an error code not selected in Status codes field, retrying stops.
- Select for how many seconds your request will wait to retry sending the next request. Most REST APIs apply rate limits depending on the subscription type or the endpoint the request is sent to. Similarly, some requests are processed asynchronously, resulting with the response code or message to be updated after a few seconds.
If you are not sure how many times to retry sending your API request or how many seconds delay to put in between each try, check in with your tool's developer documents for retries and rate limits.
If youa re looking to send an API request based on a condition, you can enable Run conditions option. The data to execute the request is evaluated against the request's conditions. If conditions are met, Actioner executes the request. If conditions are not satisfied, nothing happens.
To set a conditional logic for an API request,
- Go to Settings tab of your request
- Enable Run conditions option.
- Add filters to build your conditions will open up.
- One or more conditions below: When selected, if any one of the conditions are satisfied, it's sufficient to proceed to executing the request.
- All conditions below: When selected, if all of the conditions are satisfied, it's sufficient to proceed to executing the request. If any of them fails, request will not be executed.
When you enable Run conditions for a request, a new area with 3 boxes open up. These boxes denote in order:
- The variable to evaluate, typically a dynamic data referencing an action component's value, such as
- The functional operation that the variable is expected to comply.
- The value that the variable is expected to match.
Test and run API requests
Click green Run button next to the URL to run your request. This sends the request to the entered endpoint. This is especially important when you need to test your request's status and see its response while designing actions.
If an input is referred in request URL, params, header or body; that request can not run on Requests tab, the response will be empty. These requests referencing input components can only be sent while testing or running the action.
After running the API request, go to Response (located at the bottom of the API request) to view the response to your request. To allocate more space in order to view the response, you can collapse the request by clicking on its name.
Navigate to Body and Headers tabs to view the headers and body of the response.