Skip to main content

API requests

Learn how to configure API requests while designing your own custom actions.

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 integrations, 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 integration. 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 integration requires.

Configure API requests​

Your integration'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.

Once you have a connection schema added to your integration, 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.

Select a connection for an API request

Tip

Complete authentication for your action to better test and design your actions.

Actioner provides preset connections with the most popular integrations. It is also possible to create custom connections with generic basic authentication and generic API key options.

When you enabled Use connection option in your request, 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 Connection schema tab of your integration. Once the connection URL is updated, the base URL in your request is updated accordingly.

Tip

Using a connection schema 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 schema for any request in your integration. This saves you time with not having to enter the same URL or authentication parameters for each request.
  • Uses for different authentication types:
    • OAuth2 authentication: Actioner supports OAuth2 connection with GitHub, Jira, Zendesk, and other popular integrations. It is not possible to configure OAuth2 by setting up a request. If you are connecting with GitHub, Jira or other integrations we provide OAuth2 option, go to Connections page of your integration and add a new connection.
    • API Key authentication: To authenticate with an API key in your integration, 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 admins in your Actioner workspace.
    • 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 admins in your Actioner workspace.

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

Select a method for an API request

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 integration and you are looking to list your users in Zendesk. Your Zendesk connection's base URL is acme.zendesk.com.

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.

Enter URL for a request

If you are not sure how to enter URLs, check in with your integration'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.

4. Params​

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.

Enter Params in a request

If your request doesn't require a Headers or Body, go ahead and click the green Run button to see its response. Otherwise, continue with configuring Headers and Body of your request.

5. Headers​

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 integration'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 integration's API requires URL-encoded data, add the relative form fields on the Form URL encoded tab.

Note

There is sometimes confusion between form data and 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:

  • application/xml
  • application/xhtml_xml
  • application/json
  • application/form_urlencoded
  • multipart_form_data
  • text/plain
  • text/xml
  • text/html

Enter Body of an API request

Settings​

Retry​

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.

Retry stops
  • 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,

  1. Go to Settings tab of your request
  2. Enable Retry option.
  3. 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.
  4. 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.
  5. Select for how many seconds your request will wait to retry sending the next request. Most REST APIs integrationly 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.
Tip

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.

Run conditions​

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,

  1. Go to Settings tab of your request
  2. Enable Run conditions option.
  3. Add filters to build your conditions will open up.

Condition types​

  • 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.

Condition filters​

When you enable Run conditions for a request, a new area with 3 boxes open up. These boxes denote in order:

  1. The variable to evaluate, typically a dynamic data referencing an action component's value, such as {{input.name}}.
  2. The functional operation that the variable is expected to comply.
  3. 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.

Test a request

If an input is referred in request URL, params, header or body; that input might need to be filled out for the request to be triggered on Requests tab.