REST Queries

Compose new REST queries

Creating a new request

First, create a REST datasource if you do not have one already. For more details, see:

REST

Use the Add query button to open the query editor.

Adding a new datasource query

The new query editor

Name

Give your query a recognizable name that will appear in the datasource navigator. For example, a query that retrieves a list of applications could be called applications.

Editing the query name

URL

Enter the URL of the API endpoint you are using. The URL is the requested resource including the protocol, domain name, and path.

Adding the query URL

Method

Select the HTTP method used by the API endpoint you are using.

• GET retrieves data from an API.

• POST sends new data to an API.

• PATCH and PUT update existing data.

• DELETE removes existing data.

Access level

Select the access level required by the logged-in end-user. If the user visits a page where a query is executed and the access level is beyond the scope of the user's access the query will not run.

Params

URL parameters can be configured in the params tab.

• Parameters are appended to the end of the request URL, following ? and listed in key value pairs, separated by & using the following syntax: ?status=all&other=value

• Parameters can be hardcoded or they can use bindings or variables.

Adding a URL parameter

Bindings

Use bindings to supply additional information to the query at runtime. Using the params example from above we can replace the hardcoded value of all with a binding named status that has a default value of all. Now we can change the value of status by supplying it from within an application using the query.

Adding a binding

For more information on using REST bindings see:

REST Bindings Example

Headers

Use headers to supply key-value pairs accepted by your API.

• Switch the Active toggle to off to prevent the headers from being sent while keeping it's configuration.

• Headers can be hardcoded or they can use bindings or variables.

Adding a header

Body

Use a request body to send information to an API endpoint.

Sending a json body

• The Content-Type header will automatically be set when using:

  • raw(JSON) / application/json

  • raw(XML) / application/xml

  • raw(Text) / text/plain

• If you manually select a Content-Type header, that value will be overridden by the body type

• The body can be hardcoded or it can use bindings or variables.

Transformer

Transformers can be used to augment the format of the returned data.

A REST query transformer

For more information on using query transformers see:

Transformers

Authentication

Preset authentication strategies configured at the REST datasource level can be used to authenticate queries.

For more information on using REST authentication see:

REST Authentication

Sending the request

When your query is crafted you can use the Send button to preview the results of your query. When your query has been successfully executed you may save the query using Save Query

Previewing the results of a query

Using response data

When a query has run successfully the response data can be actioned on to better fit the usage in your application.

Modifying the schema

The response schema may be updated by:

• Adding or removing fields

• Changing the data type used when displaying the result in tables

The response schema

Creating dynamic variables

The response schema and headers can be used to create dynamic variables

Creating body based variables

Creating header based variables

For more information on static and dynamic variables see:

REST Variables