API Calls

On FlutterFlow, you can build applications to interact with thousands of external services using their APIs.
If you are brand new to APIs, you may want to check out this in-depth APIs for beginners tutorial video.
What is an API?
The acronym API stands for Application Programming Interface. It lets a product or service (in this case it's the app that you are building ) communicate with other products and services through a secured channel without sharing much information about their implementation.
The two most popular API specifications are SOAP and REST. We won't go into much depth about these here, just to give you a brief idea:
​SOAP: Also known as Simple Object Access Protocol that uses XML for their message format and receives requests through HTTP or SMTP.
​REST: Acronym for Representational State Transfer is an architectural style followed by various APIs. REST APIs are known for their fast performance & reliability.
Most of the Web APIs that you will be dealing with are in REST with JSON format as this is the most predominant specification now.
Methods of API Call
While defining a REST API Call, you will need to specify the type of HTTP request method to use. 
You can select among the following method types while defining an API Call on FlutterFlow (expand the section to learn more):
GET request (Read data)
POST request (Create data)
DELETE request (Delete data)
PUT request (Replace data - updates the entire data)
PATCH request (Modify data - helps in partial update)
Headers
Headers typically carry the metadata associated with an HTTP request or response of an API call. HTTP headers are mainly grouped into two categories:
Request headers contain more information about the resource to be fetched, or about the client requesting the resource.
Response headers hold additional information about the response that will be returned by the server.
While defining an HTTP request, the Header that you will be defining is called the Request header.
Some of the common Headers that you might need while sending a request are:
Authorization: Used for authenticating the request by the server.
Content-Type: Used while sending a POST request containing a message body.
The default Content-Type for any HTTP POST request is application/json, so if your data body is in JSON you can skip defining the Content-Type.
You can define a header while defining any API call on FlutterFlow, click on the Add Header button and enter the Name and Value for the header.
Following is an example of adding an authorization header for sending an email using SendGrid Email API.
Query Parameters
They are optional parameters that you can pass with an API call, they help in formatting the response data returned by the server. Usually, they are concatenated at the end of the URL with a question mark (?) as the delimiter and are represented as key-value pairs.
An example of an URL with query parameters look like this (NASA Open API):
​https://api.nasa.gov/neo/rest/v1/feed?start_date=2015-09-07&end_date=2015-09-08&api_key=DEMO_KEY​
Here, start_date, end_date, and api_key are the query parameters that are passed for formatting the data retrieved by this URL.
While defining a GET or DELETE API call on FlutterFlow, you can pass Query Parameters to the call by clicking on the Add Parameter button and specifying Name, Value Type, and Default Value for each parameter.
Variables
They are similar to the Query Parameters with a slight difference, variables can be used in two ways:
Passed inside the URL (by concatenating at the end of the URL with a question mark (?) as the delimiter).
Passed inside the Body of the call to use a dynamic value.
While defining a POST, PUT, or PATCH API call on FlutterFlow, you can define and use Variables inside the call by clicking on the Add Variable button and specifying Name, Value Type, and Default Value for each variable.
Body
You can send data while performing an HTTP POST, PUT, or PATCH request by defining them inside Body. The JSON format is the easiest way of passing data inside the body of the request.
If you have defined any variable, you can use them inside the body by dragging and dropping them as values of any keys inside your JSON.
JSON Path
JSONPath is a query language for JSON. You can use a path (or JSONPath expression) to retrieve the value of certain property from a JSON response (you'll usually get a response in this format from an API request).
Some examples of JSONPath expressions are as follows:
$.data.name
$.users[0].name
The leading $ represents the root object, dot (.) is used for accessing properties present inside the JSON, the value inside brackets ([0]) represents the array index if the property contains an array.
Learn more about JSONPath and how to define a proper expression from this page.
While accessing values from an API Call inside the FlutterFlow app (by defining an Action or a Backend Query) you'll need to use JSONPath. To find the correct path from a JSON response, check out the Testing API Calls section.
Add API Calls
In order to use an API in your app, first, you have to add the API Call that you want to use on FlutterFlow.
Follow the steps below to add an API Call:
1.Go to the project on FlutterFlow in which you want to add the API Call.
2.Select API Calls from the left Navigation Menu to go to the API Configuration page.
3.Click Add API Call button.
4.Enter a name for the API Call. 
5.Select the Method Type: GET, POST, DELETE, PUT, or PATCH.
6.Enter the API URL of the service you want to access.
NOTE: If you want to use a dynamic URL, wrap that portion in brackets and add it as a Query Parameter (if using GET or DELETE) or a Variable (if using POST, PUT, or PATCH).
Defining GET & DELETE call
If you have selected GET or DELETE as the method type, follow the steps below:
1.(Optional) You can click on Add Header to add a header to the API Call if it requires any.
2.(Optional) You can pass parameters to the API call from the UI Builder, click on Add Parameter to define a parameter.
3.(Optional) To test an API Call, go to the Response & Test tab. Know more about testing an API call here.
4.Finally, click Add Call to save the API Call.
NOTE: You can add multiple headers and parameters to the same API Call.
In the above demo, a GET API call is defined to fetch users' data from REQ | RES (which provides hosted REST API to try out HTTP requests).
A demo of using dynamic URL in a GET request is as follows:
In this demo, a URL is defined for fetching a single user using an ID. A parameter is defined under Query Parameters, called user_id that specifies an ID for the user to fetch.
The DELETE API Call can also be defined similarly, just make sure you select the Method Type as DELETE.
Defining POST, PUT & PATCH call
If you have selected POST request, follow the steps below:
1.(Optional) You can add a header to the API call (if required) by clicking on Add Header, and then setting a Name and a Value to it.
2.(Optional) You can pass Variables to the API call by clicking on Add Variable. Specify a Name and Value Type of the variable, you can also set a Default Value to it.
3.Select the type of data that you want to send in the POST request under Body.
4.Enter the data to be passed inside the text box present under the body type. For example, if you have selected JSON as the body type, enter the JSON data to be passed.
5.(Optional) To test an API Call, go to the Response & Test tab. Know more about testing an API call here.
6.Finally, click Add Call to save the API Call.
In this demo, a POST API call is defined that has two variables userName and userJob. The variables are used inside the JSON passed as the Body to this call.
The PUT and PATCH API calls can be defined similarly, just make sure you are entering a valid API URL endpoint and the correct Method Type is selected.
Some important points to keep in mind while defining an API Call:
Most APIs require authentication to access their server, authentication data (for example, API KEY) is usually passed in the Header of the API call. Follow the API Docs of the particular service that you are using to get the proper format of passing the data.
In POST, PUT, and PATCH requests, you can use the Variables inside the data Body that you want to pass to the API call.
In POST, PUT, and PATCH requests, you can format the data body that you enter inside the text box by clicking the Format button.
Testing API Calls
You should always test an HTTP request before using it inside your app. FlutterFlow makes it easy to test out any API Call directly on its webpage.
To test an HTTP request along with its response follow the steps below:
1.Select an API call that you have already defined or you're currently defining, go to the Response & Test tab.
2.Under the Test Values section, enter the values for the Parameters if you have defined any for that API Call.
3.Click Test API Call to trigger the API call. You'll notice that the status of the GET request is displayed and if it's successful (status code of 200) then the result returned from that request will also be displayed below.
4.Any value of the JSON result can be accessed by defining its correct path. Select JSON Path Name as Custom and define the Path.
5.Another way is to define the paths under the Define JSON Paths section by specifying the name and its respective path. Then select the respective path from the dropdown under JSON Path Name.
Testing a GET API Call
The above demo shows the testing of a single user GET request by providing an ID. You can also see how a JSON Path is defined to retrieve a specific value. The successful GET request returns a status code of 200.
The testing of DELETE request would be similar to this.
​
Testing a POST API Call
The above demo shows the testing of creating a new user using a POST request. The API Call takes two variables: userName and userJob. The variables are also used inside the body to dynamically insert the values in the JSON. The successful POST request returns a status code of 201.
The testing of PUT and PATCH requests would also be similar to this.
Trigger API Calls
There are two methods that you can use to trigger an API Call in your app:
Add an Action to trigger the API Call based upon a user gesture.
Add the API Call as a Backend Query that gets triggered automatically once a user navigates to the page.
You will find the steps for triggering API Calls using either of these two methods in the following pages:
​Action for triggering an API Call​
​Backend Query for triggering an API Call​