Making API requests

You can make requests to any HTTP API in Retool.

You can make requests to any HTTP API in Retool. A common workflow: GET data from your own internal APIs, render the data in a Table component then POST data (such as resetting passwords) back to your own API. Other common workflows include:

  • Making an API request to a REST resource for an internal API with custom auth.
  • Making a one-off API request with a REST query to public APIs, i.e. Google Places API.
  • Uploading a file via a POST request.
  • Making an API request to APIs that support SOAP, i.e. Bing Ads API.

REST APIs

REST APIs in Retool follow familiar specifications:

  • URIs (Uniform Resource Identifier, i.e. /wiki/what_is_an_api)
  • HTTP protocols
    • GET to retrieve data
    • POST to write new data
    • PATCH to update existing data fields
    • PUT to replace existing data
    • DELETE to delete existing data
  • JSON as a data format for both request and response data

Connecting to a REST API

There are two ways to query a REST API in Retool:

  1. Add the REST API via the resources page to reuse across multiple apps
  2. Use the RESTQuery type in an app

Querying a REST API

Whether you’ve connected a resource or added a URL directly into the query editor, you can send path and URL parameters using the URL field of the Query and the URL Params section:

  • You can include path parameters as part of the URL, and reference using placeholders such as the following: /users/{{ table1.selectedRow.data.id }}
  • You can list URL parameters in the URL Params section — they will be appended at the end of the URL, following ? and listed in key value pairs, separated by & (i.e. ?id=1&type=new)

Here is an example GET request:

Note we’re using curly braces to write Javascript that references the currently selected row of a table component (table1). You can write that JS in the URL parameters fields, and it will automatically translate to the URL.

For POST , PATCH, and PUT requests, you can include a request body under the Body section to send data along with your request.

Using JSON body in API requests

To start constructing a JSON request body, select JSON in the Body section of the request template. You will see that you can easily construct a JSON object using the key-value interface provided.

To create a more complex structure, you can nest objects as children of a key like below:

Alternatively, you can also switch from the key-value interface and construct your own JSON object. To do this, you will need to specify the Content-Type header to application/json, and select Raw under the Body section of the request template. Here is an equivalent query to above.

📘

Formatting JSON can be a little confusing at first!

  • For a value that should be a string, make sure to wrap the {{ }} with double quotes.
  • For a value that is a boolean / number, do not wrap the {{ }} with double quotes.
  • For a value that is an object / array, wrap the value inside with a JSON.stringify()

Since it can be a confusing at times to correctly format your JSON body, you can alternatively wrap the entire body in curly braces to construct the object dynamically.

For data that’s difficult to format as a JSON (i.e. an image or audio file), you can still send these through your API via a POST request. Let’s take a look at a couple examples below.

Uploading a file via a POST request

Retool current supports two methods for uploading files: using a form or as a binary file without any metadata

via Form Data body

You can upload a file by attaching files via Form Data in the request body.

Here is an example REST query that uploads using a file using form data:

via binary body

You can use binary data to send data that you can’t manually enter in the request body section of the query editor (i.e. image / audio / video / even text files).

Here is an example REST query that uploads a binary:

You can hook these queries up to a button, too. Below is an example of how to set up a filepicker button that allows users to select a file from their computer to upload. Once the file has been selected, the REST query uploadFile will run and upload the chosen file. If you drag a filepicker onto the canvas and click on it, you should see a “After file selected” field in the right sidebar: choose your upload query from the dropdown.

SOAP APIs

If you are planning to create a SOAP API resource, you can create one the same way you create a REST API resource.

To send a SOAP API request with Retool:

  1. Use the SOAP endpoint as the URL of the request. If you are using a web services description language (WSDL), then you must give the path to the WSDL inside the URL.
  2. SOAP endpoints respond to POST requests, so set the request method to POST.
  3. Add the header Content-Type = text/xml
  4. In the body, change the body type to Raw, then define the SOAP Envelope, Header and Body tags as needed.
  5. Consult your API specification for the headers required. The name of the SOAP method is usually specified in the SOAP body, but sometimes it may be specified in the header.

Here is an example Retool SOAP API request:

FAQs

Can Retool handle sending thousands of requests via a single REST query? What would the frontend display while this goes on?

Yes! The query status on the query would be {{ query.isFetching }} equals true. You could disable other components when {{ query.isFetching === true }} so that the components that automatically depend on query1 should just have a loading indicator over them by default.

Can I send a request to a locally-hosted API with Retool?

Unfortunately, you aren’t able to ping endpoints running on localhost. There are a couple workarounds you can try:

How do I access the response headers of my REST query?

You can access the response headers, along with all of the response metadata! Just use {{query.metadata.headers}} anywhere in your Retool app.

Some of the error messaging from my queries are vague. How can I get more info?

We are focusing on polishing up some of these aspects of Retool over the next few months — if you see anything egregious, let us know at [email protected] and we’ll be sure to inform you when it is fixed!

Can I use JWT tokens for authenticating my REST API in Retool?

Unfortunately, Retool doesn’t have an out-of-the-box solution for authenticating with JWT tokens. A workaround is to use a custom REST API request for the authentication (instead of putting authentication into the resource), then use javascript functions to decode and encode the JWT token.

Updated about a month ago


Making API requests


You can make requests to any HTTP API in Retool.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.