REST APIs
With Appsmith, you can connect to a wide range of tools and platforms. If you want to connect to an API or if there isn't a native integration with a datasource on Appsmith, you can connect through the REST API interface.
If the API is protected by an authentication mechanism that requires a standard set of headers or parameters that need to be sent with every request, you can save these in a common datasource that can be reused with every request known as Authenticated API datasources.
Appsmith encrypts all your datasource credentials and stores them securely. Appsmith also doesn't store any data returned from your datasources and acts only as a proxy layer to orchestrate the execution of Queries. As Appsmith is an open source framework, you can deploy it on-premise, and audit it to ensure none of your data leaves your VPC. For more information, see Security.
Connecting to REST API
To connect to a REST API, go to the Explorer tab, click the + icon next to Datasources and select REST API.
You can provide the URL and additional information like the Headers, Params, Body, and Pagination. After adding the request details, you can directly run the API query and bind it to widgets to display the results in the UI. To learn more about setting API request details, you can refer to the documentation on configuring APIs.
Sample API
Appsmith provides a sample API https://mock-api.appsmith.com
to help you learn to create and modify queries using the REST API pane.
To use the sample APIs:
- Go to the Explorer tab, click the + icon next to Datasources.
- Select REST API
- To fetch users data from this API choose the
GET
method and enter the following URL:
https://mock-api.appsmith.com/users?page=1
- Click the Run button to execute the API query and view the response.
Creating an authenticated API datasource
When you create an authenticated API datasource, you need to configure the headers and query parameters only once and thereafter don't need to configure these for every API request. Additionally, to ensure authorized access and secure data transfer, various authentication mechanisms can be implemented, such as OAuth 2.0, signature headers, self-signed certificates, bearer token-based authentication, and API key-based authentication.
To create an authenticated API datasource:
On the Explorer tab, click the + icon next to Datasources
Select Authenticated API.
Click the edit pencil icon next to the default name to rename the datasource.
Provide the configuration details required to connect to your API.
- Name: Specify a name for the API datasource.
- Method: Select the method for the API request.
- URL: Specify the URL for the API endpoint.
- Headers: Set the required HTTP headers for the API request.
- Query parameters: Provide the query parameters for the API request, if necessary.
- Authentication type: Define an authentication type for REST APIs by using the protocols available on Appsmith.
- Send appsmith signature header: Ensure that the incoming requests originate from Appsmith.
- Use self-signed certificate: These certificates can be configured as part of the Advanced Settings.
Save the datasource. The configuration details aren't saved/updated until the Save button is clicked. When the datasource has been added successfully, a success message appears at the top of the app window.
If you want to connect to an API that's not publicly available on the internet, you can use a service like ngrok to expose it. For more information, see How to work with local APIs on Appsmith.
Importing cURL commands
cURL is a command-line tool that can be used to make HTTP requests to a server. You can use cURL to send HTTP requests, such as GET, POST, PUT, and DELETE, to a server to retrieve or manipulate data. Appsmith makes it easy to import your APIs into your application using cURL commands.
To import cURL commands into your application:
- On the Explorer tab, click the + icon next to Datasources
- Select cURL Import.
- Add your cURL command, for example:
curl -X GET https://example.com/resource
- Click the Import button.
Native API datasources
Appsmith can also seamlessly connect with most other tools through the RESTful API plugin. For more information, see Integrations
Passing parameters to API requests
There are three ways to pass parameters to API calls on Appsmith as shown in the video below:
Send body data with API requests
Appsmith supports a variety of encoding types for sending data in API queries. The encoding type can be selected via the Body dropdown on the API editor. Selecting NONE omits a body from the request.
URL-encoded form data
Selecting the value FORM_URLENCODED (for application/x-www-form-urlencoded
) automatically encodes your key/value pairs to be sent in the body field.
Multipart/Form-data
Multipart requests can include several different types of data within them, such as a file along with some other related metadata. To set up your query to send with multipart/form-data
encoding, navigate to its query editor screen, click the Body tab, and find the MULTIPART_FORM_DATA tab beneath it.
To submit a file as a multipart input, use a Filepicker widget to upload a file to your application. Once it has been uploaded, you can bind {{ FilePicker1.files[0] }}
as a value in your API's multipart request body. Be sure to select "File" in the datatype dropdown. If you would like to submit multiple files in the same request key, you can alternatively use {{ FilePicker1.files }}
to include the entire contents of the Filepicker widget.
The file data from the Filepicker widget can be in any data format (base64 or binary) according to the requirements of the endpoint that you're connecting to.
You can also pass plain text values in your multipart request by selecting the "Text" option in the datatype dropdown. If you wish to pass multiple plain text values under the same key, be sure to use the "Array" option instead.
// type: Text
{{ Text1.text }}
// type: Array
{{[ Text1.text, Text2.text, "hello, world"]}}
Raw data
If your endpoint can't accept multipart-encoded data and requires raw body binary instead, choose the RAW tab under the query Body tab instead of MULTIPART_FORM_DATA. In this case, you would pass the data
property of your file to the query instead of the file object itself, because the endpoint expects only raw binary data:
// Binary data in the RAW format
{{ Filepicker1.files[0]?.data }}
The preceding example uses Optional Chaining using the ?
operator. This way, if the files[0]
doesn't exist, attempting to access data
returns undefined
instead of raising an error.
Be sure to turn off the JSON Smart Substitution setting for this query in the query settings. This option is useful for helping to cast data into the correct JSON formats, however it can be problematic when used with RAW body binary encoding.
Troubleshooting
Are you having trouble? check out the API response troubleshooting guide or reach out on Discord to get support or ask questions on the community forum.