This tutorial explains how to set up and configure the Rest Request Action in Onit to interface with external API endpoints. Onit’s Rest Request Action allows you to make GET, PUT, POST, and DELETE actions against an API.
There are many use cases for a Rest Request Action including creating records with a POST, gathering information with a GET, and deleting information with a DELETE request. A Rest Request Action must be utilized with a Business Rule, Button, or Conditional Compound Action (CCA) in order to fire.
To complete this tutorial, you will need:
- An App that you can make changes to.
- An API to call against. In this tutorial we have used a very basic example API named JSONPlaceholder. This API returns sample "posts" from users with a randomly generated title and body.
Configuring the REST Request Action
Browse to the Advanced Designer page for your App. Here we will be demonstrating a GET request in our App named User Posts. All of the configuration in this tutorial will be done inside of the Rest Request Action.
-
Go to the Actions node and create a new Rest Request.
-
On the Action screen fill in the API’s URL into the URL property. The URL you enter should be the endpoint URL of your API. Do not include any request parameters here. The endpoint we will be using is https://jsonplaceholder.typicode.com/posts/1. This endpoint will return one test "post" when we call the REST Request Action.
-
The Call property is where you tell Onit the type of request to make. The options are:
- GET: Used to request data from a resource.
- POST: Used to create a new resource.
- PUT: Used to update a resource.
- DELETE: Used to delete a resource.
For the purposes of this tutorial set the Call property to GET.
- By default, the headers property will be `accept:json`. This will only change if there are specific header requirements for your API endpoint. For now, we will leave `accept:json`.
- Enter parameters in the Liquid Params property. This property accepts parameter key:value pairs where the value may be Liquid. Our API does not require any Liquid Params so we will leave this property blank.
- If your API endpoint requires a body, enter it in the Body JSON property below. An HTTP message body transmits bytes immediately following the headers. In most cases the body is used to create or modify existing resources. Our API does not require a body, so we’ll leave this blank.
-
Under Status Field we will choose a pre-created Field named User Response to hold our API response. This Field does not have to be visible to users, as often it will be used for logic purposes.
Note: The Status Field will contain the raw JSON response from your API unless you specify a custom success or failure message in the Success Status Message and Error Status Message Fields below (in which case the message you enter will appear in place of the JSON).
If you would like your Status Field to contain something other than a raw JSON API response, this is where you would fill in your success and failure messages.
Below are some common response codes and how Onit interprets them:
| Code | Code Meaning |
Onit Success or Failure? |
|---|---|---|
| 200 | OK | Success |
| 201 | Created | Failure |
| 400 | Bad Request | Failure |
| 401 | Unauthorized | Failure |
| 403 | Forbidden | Failure |
| 404 | Not Found | Failure |
| 500 | Internal Server Error | Failure |
- Click Ok to save your Action.
Configuring REST Response Paths
If the goal of the REST Request Action is to ensure that the request successfully POSTs a record at the targeted endpoint, then the Action must be configured to handle both the successful and unsuccessful responses. In order to do this, often it is necessary to create a Conditional Compound Action (CCA) Action where the Rest Request Action is the first Action, and then there are defined “success” and “failure” CCAs that follow the Rest Request.
This allows you to further update the App or hang logic off of the success or failure of the Action. For instance, in the event of a failure response code such as a 404 or 403 error, you can then fire a Looped Action that will continue to try the response a certain number of times, while in the event of a success, you can change the Phase of the transaction.
JSON Liquid Filter
The parse json Liquid filter allows you to sort through JSON and retrieve specific information. For example, you could use the parse_json Liquid filter to determine the status code of a response from an endpoint.
To do so, first assign a variable to the Field that contains the API response, then pipe it through the filter:
{% assign parsed_json_variable = name_of_your_response_field | parse_json %}To capture the response code given by the API you will need another variable:
{% assign status_code = {{parsed_json_variable["code"]}} %}To check if the status code returned is 201, for example, you could include an if statement in your Liquid:
{% if status_code == "201" %}true{% endif %}The full Liquid filter to determine if the status code is 201 is as follows:
{% assign parsed_json_variable = name_of_your_response_field | parse_json %}{% assign status_code = {{parsed_json_variable["code"]}} %}{% if status_code == "201" %}true{% endif %}
Testing the REST Request Action
The steps below provide an example of how you might test your Rest Request Action to ensure that it’s working correctly. Below we have configured an App to make API calls upon a Record’s Phase change and then store the API response in a visible status Field.
Note: You can use a REST client like Postman or AdvancedRest Client to test out your full requests to make sure they are correct before you build out the Rest Request Action. This is highly recommended, as it makes troubleshooting much easier.
- Determine if you want to test a success or failure response.
- Trigger the REST Request Action.
- Check your response Field to make sure that you received the response you were expecting. If you have specified a custom success/failure message, ensure that it shows in the correct Field.
