Learn how to connect and query REST APIs in Retool.
You can make requests to any REST, GraphQL, or SOAP API. You can also use custom authentication to interact with private REST or GraphQL APIs, such as internal APIs.
Connect to a REST API
You can connect to a REST API in two ways:
- Create a resource to connect the API to Retool. This allows you to configure the API once so it's available as a resource anywhere in Retool. You can also configure additional authentication options, if required.
- Use the built-in RESTQuery (restapi) resource and manually write API requests. This is useful if you only need to query an API temporarily and won't use it elsewhere. You must manually define API endpoints, authentication options, and any other parameters in each query.
Query a REST API
You can select a REST API resource in your Retool organization from the Resource field in the query editor. After selecting the resource, the configured API endpoint appears in the URL field. You can then specify the parameters and other options in the available fields.
To interact with a REST API that is not configured as a resource, select the RESTQuery (restapi) resource from the Resource field in the query editor. You manually define the API endpoint and other parameters in the available fields.
Action types
Retool supports the following request methods for REST APIs:
- GET
- POST
- PUT
- PATCH
- DELETE
You specify the method to use by selecting an option in the Action type dropdown.
Queries using GET methods automatically run whenever any of their parameters change by default (e.g., input field value changes). Queries using POST, PUT, PATCH, and DELETE methods must be manually triggered by default. You can choose whether a query should run automatically or manually in the query editor; select Run query only when manually triggered or Run query automatically when inputs change in the dropdown menu.
Path and URL parameters
You can include additional path and URL parameters to any API request in the query editor. Path parameters can be included directly in your URL, and URL parameters can be added in the URL parameters section. Path and URL parameters can also read from values within curly braces ({{ }}).
When you specify URL parameters, Retool automatically appends them to the endpoint URL. Conversely, Retool detects any URL parameters added to the endpoint URL and populates the URL parameter fields.
The following example shows a GET request which reads the currently selected row of a Table component and passes it as a URL parameter with a key of id.
Request headers
For REST APIs configured as a resource, you can set request headers on the resource's configuration page. Headers set on resource configuration pages are always included on any requests using that resource.
You can also add headers to any request using the Headers fields in the query editor. These headers are included in addition to any already configured for the resource.
note
Retool sanitizes any headers with keys that contain authorization, key, or password.
Request bodies
You can send requests with JSON, raw, x-www-form-urlencoded, Form data, or binary bodies.
JSON
To construct a JSON request body, select JSON in the Body section of the query editor. You can then construct a JSON object using the key-value fields. A Content-Type: application/json request header is automatically added to requests using JSON body types. The JSON body also supports nested objects within a single key.
Raw
To send a request body without modifications, select Raw in the Body section of the query editor. For example, if you use the Raw body type and manually add a Content-Type: application/json header, you can send more complex JSON objects.
You can include JSON in raw request bodies with some additional formatting. You can either wrap the entire body in curly braces to construct the object dynamically or manually format values in the following ways:
- String values: Wrap values in curly braces
{{ }}with double quotes. - Boolean or number values: Do not wrap curly braces
{{ }}with double quotes. - Objects and arrays: Use
JSON.stringify()to convert to string values.
x-www-form-urlencoded
To send URL-encoded data, select x-www-form-urlencoded in the Body section of the query editor. Retool adds Content-Type: application/x-www-form-urlencoded to the request header.
Form data
tip
See the guide to handling files in Retool to learn how Retool represents files.
To send form data in your request, select Form data in the Body section of the query editor. A Content-Type: multipart/form-data header is added to the request.
To upload a file using form data, set a key to file, select the File upload type, and set the value to the file to upload. The .value property on File Input, File Button, and File Dropzone components has the correct schema for file uploads. For example, set value to {{ fileInput.value }} to upload a file as form data.
Binary
To send data that can't be formatted as form data—for example, an image, audio, or video—select binary in the Body section of the query editor.
The following examples passes the File button upload value as binary data.
Cookies
You can configure REST API resources to use cookies-based authentication for REST API resource support cookies for API authentication. You can also add cookie headers to API requests using the Cookies key-value field in the query editor.
