API Calls 101

On this page, you will learn the most basic knowledge on various concepts for adding an API call to your project. They are the building blocks of adding an API call. You might use some or all of them based on the API definition.
Here are they:
​Headers​
​Query Parameters​
​Variables​
​Body​
​JSON Path​
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 the client requesting the resource.
Response headers hold additional information about the response that the server will return.
Passing request headers
Some of the common request headers that you might need while sending a request are:
Authorization: Used for authenticating the request.
Content-Type: Used while sending a POST/PUT/PATCH request containing a message body.
To pass the request header:
Select the Headers tab and click on the + Add Header button.
Inside the input box, enter the header name followed by colon(:) and its value (e.g., Content-Length: application/json). 
Passing request header
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.
Passing auth token (as request header)
You might need to add an API that is secured. That means it only gives results if you pass the authorization token (aka auth token) in the header parameter. This is usually done to prevent abuse. Let's see how you can add the auth token.
Passing static auth token
Some services provide you with a static auth token. Such a token never changes until you manually generate the new one.
To pass the static auth token:
Select the Headers tab and click on the + Add Header button.
Inside the input box, enter the header name as Authorization followed by colon (:) and its value (e.g., Authorization: Bearer YOUR_TOKEN). 
Passing static auth token
Passing dynamic auth token
You would probably like to pass the auth token returned as a response in the login API call. Such a token changes every time when you log in. Hence, you need a way to pass the dynamic token.
After the login call is succeeded, ensure you save the authentication token in a local state variable (with Persisted -> True). Check the visuals below:
Creating a local state variable to save a token
Saving a token
To pass the dynamic token:
Select the Headers tab and click on the + Add Header button.
Inside the input box, enter the header name as Authorization followed by a colon (:) and then enter any variable name inside the brackets (e.g., Authorization: Bearer [auth_token]).
Select the Variables tab and create a new variable with the same name you provided inside the brackets. This will be used to pass the token value from the local state variable to the API call.
Now from the API call (that requires an authentication token), pass the token value from the local state variable.
Passing dynamic auth token
Accessing response headers
Sometimes you might want to retrieve the values of the response headers. For example, retrieving the auth token from the response headers of the Login API call.
To access the response header:
Ensure you have added the API call action and provided the Action Output Variable Name.
Now, whenever/wherever the Value Source is set to From Variable, select the Action Outputs > [Action Output Variable Name] (e.g. Action Outputs > loginResponse).
Set the API Response Options to Get Response Header.
Enter the Header Name. This must match the name of the response header from your API call.
Click Confirm.
Accessing response headers
Query Parameters
They are optional parameters you can pass with an API call; they help format 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 looks 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 passed to receive the specific data.
Here's another example, this API call https://www.breakingbadapi.com/api/characters?limit=20&offset=0 has two query parameters. The limit parameter specifies 20 items to load per page, and the offset specifies the number of items to skip. This is called offset-based pagination.
Passing query parameters
To pass the query parameters for GET or DELETE API call:
Select the Query Parameters tab and click the + Add Query Parameter button.
Enter the Name of the query parameter. 
Set the Value Source to Specific Value or From Variable.
If you want to pass this value from your page, local state variable, or any other source (i.e., dynamic value), choose the From Variable, and then from the Select Variable dropdown, choose the already created variable (see how to create variable) or click on + Create New Variable. Note: This will immediately create a new variable with the same name as of query parameter. However, you still need to open the Variables tab and set its Type.
If you want to pass a static/fixed value, select the Specific Value, set its Type, and enter its Value.
Below is the example of passing query parameter for the URL -> https://api.instantwebtools.net/v2/passenger?page=10&size=20
Passing query parameters for GET and DELETE API calls
In a rare case, you might want to pass the query parameters for the other methods of API calls. Such as POST, PUT, and PATCH. To do so:
In your API URL, replace the hard-coded values with a meaningful name inside the brackets (e.g., from https://api.instantwebtools.net/v2/passenger?page=0 to https://api.instantwebtools.net/v2/passenger?page=[page]).
Select the Variables tab and create a new variable with the same name you provided inside the brackets.
Passing query parameters for POST, PUT and PATCH API calls
Variables
Variables allow you to pass the dynamic values from your page, local state variable, or from any other source to the API calls. 
Here are some of the use cases where you need to create the variables:
Passing auth token from local state variable to the request header of an API call
Passing a username and password from TextField widgets on a page to the request body of an API call.
Passing selected dates as query parameters.
Creating variables
To create variables, select the Variables tab, enter its Name, select the appropriate Type and provide the Default Value if you wish to.
Variables
Now you can pass values to these variables while triggering the API call from your page. You can set its value from any widget, local state variable, or any other source.
Passing values to variables
Body
You can send data (as request body) while calling the API of methods POST, PUT, or PATCH by defining them inside Body. The most common type is JSON format which is the easiest way of passing data inside the body of the request.
Creating request body
Here you'll see creating a request body for JSON and x-www-urlencoded format.
JSON format
To create a request body in JSON format:
First, If you haven't already, create variables (e.g., username and password variables that will be required to pass values from a login page to the login API call).
Select the Body tab and set the Body dropdown to JSON.
Copy-paste your request body and replace the values with the variables by dragging and dropping them inside your JSON body.
Creating JSON request body
Text format
This format is used to send textual data in the request body of an API. For example, in a SOAP API, the request body is typically in text format and contains XML data.
To create a request body in text format:
1.First, If you haven't already, create variables.
2.Select the Body tab and set the Body dropdown to Text.
3.Copy-paste your request body and replace the values with the variables by dragging and dropping them inside the request body.
Creating Text request body
x-www-urlencoded format
To create a request body in x-www-form-urlencoded format:
First, If you haven't already, create variables (e.g., username and password variables that will be required to pass values from a login page to the login API call).
Select the Body tab and set the Body dropdown to x-www-form-urlencoded.
Click on the + Add Parameter and enter the Name of the parameter. 
Set the Value Source to Specific Value or From Variable.
If you want to pass this value from your page, local state variable, or from any other source (i.e., dynamic value), choose the From Variable, and then from the Select Variable dropdown, choose the already created variable (see how to create variable) or click on + Create New Variable. Note: This will immediately create a new variable with the same name as of parameter. However, you still need to open the Variables tab and set its Type.
If you want to pass a static/fixed value, select the Specific Value, set its Type, and enter its Value.
Creating request body in x-www-form-urlencoded format
Multipart format
A multipart request body is a data format used in HTTP requests that enable the transfer of multiple parts of data in a single request. It is commonly used in file uploads.
To create a request body in the multipart format:
1.Select the Body tab and set the Body dropdown to Multipart.
2.Click on the + Add Parameter and enter the Name of the parameter. 
3.Set the Value Source to From Variable, and then from the Select Variable dropdown, click on + Create New Variable. Note: This will immediately create a new variable with the same name as of parameter.
4.Now move to the Variables tab and set the Type to Local File. This will allow you to pass the file stored locally on the device using an action such as Upload Photo/Video.
Creating request body in multipart format
JSON Path
JSONPath is a query language for JSON. Using the JSON path, you can retrieve specific data out of the whole JSON response.
You'll usually get a response in JSON format from an API request.
Learning a few JSON paths (or JSONPath expressions) will help you retrieve most of the data you need. Inside our builder, we allow you to try and add different JSON paths in real time and suggest various options to get exactly what you are looking for
Some examples of JSONPath expressions are as follows:
$.data.name
$.users[0].name
$.users[:].name
The leading $ represents the root object, dot (.) is used for accessing keys present inside the JSON, the value inside brackets ([0]) represents the array index if the key contains an array, and the ([:]) will select all the objects inside the list.
Let's see some real-world examples of the JSON path for the following API response:
1
{
2
  "page": 1,
3
  "per_page": 6,
4
  "total": 3,
5
  "total_pages": 2,
6
  "data": [
7
    {
8
      "id": 1,
9
      "email": "[email protected]",
10
      "first_name": "George",
11
      "last_name": "Bluth",
12
      "avatar": "https://reqres.in/img/faces/1-image.jpg"
13
    },
14
    {
15
      "id": 2,
16
      "email": "[email protected]",
17
      "first_name": "Janet",
18
      "last_name": "Weaver",
19
      "avatar": "https://reqres.in/img/faces/2-image.jpg"
20
    },
21
    {
22
      "id": 3,
23
      "email": "[email protected]",
24
      "first_name": "Emma",
25
      "last_name": "Wong",
26
      "avatar": "https://reqres.in/img/faces/3-image.jpg"
27
    }
28
  ],
29
  "support": {
30
    "url": "https://reqres.in/#support-heading",
31
    "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
32
  }
33
}
$.total
This will return the following data:
3
$.data
This will return the following data:
[
   {
      "id": 1,
      "email": "[email protected]",
      "first_name": "George",
      "last_name": "Bluth",
      "avatar": "https://reqres.in/img/faces/1-image.jpg"
   },
   {
      "id": 2,
      "email": "[email protected]",
      "first_name": "Janet",
      "last_name": "Weaver",
      "avatar": "https://reqres.in/img/faces/2-image.jpg"
   },
   {
      "id": 3,
      "email": "[email protected]",
      "first_name": "Emma",
      "last_name": "Wong",
      "avatar": "https://reqres.in/img/faces/3-image.jpg"
   }
]
$.data[0]
This will return the object at the 0th index (i.e., the first object).
{
   "id": 1,
   "email": "[email protected]",
   "first_name": "George",
   "last_name": "Bluth",
   "avatar": "https://reqres.in/img/faces/1-image.jpg"
}
$.data[0].email
This will return the email value of the object at the 0th index.
"[email protected]"
$.data[:].email
This will return the email of all the objects inside the data.
[
  "[email protected]",
  "[email protected]",
  "[email protected]"
]
Learn more about JSONPath and how to define a proper expression from this page.
Adding JSON Path
To add JSON path:
First, create and test your API call.
Inside the JSON Paths section, click on the + Add JSON Path.
Enter your JSON Path and give it a Name.
If you entered the valid expression, you'd see the starting part of the response under the Response Preview column. To see the complete response, click on the Preview icon.
If the returned response is a list of items, by default, Is List would be checked; however, if you want to convert the response into the list explicitly, checkmark it.
We also recommend all the possible JSON paths (under the Recommended tab) that might include what you are looking for.
To add the recommended JSON path, checkmark the Selected, open the Selected tab and give it a name.
Adding JSON Path
Using JSON Path
While accessing values from an API Call, you can either enter the custom JSON path or use the already created JSON path.
To use the already added JSON path:
Select your API response.
Set the API response Options to JSON Body.
Set the Available Options to JSON Path.
Set the JSON Path Name to the one that you created earlier.
Using JSON Path
Advanced Settings
You can make the API call private and change the proxy settings using advanced settings.
Making an API call private
Making an API call private is helpful if it uses tokens or secrets you don't want to expose in your app. Enabling this setting will route this API call securely via the Firebase Cloud Functions.
To make the API call private, open the Advanced Settings tab, turn on the Make Private toggle, Click Save and then Deploy APIs.
Optionally, you can force a user to be authenticated via the Firebase authentication to make this API call. To do so, turn on the Require Authentication toggle. 
If you make the API call private, Firebase should be connected to your project. Follow the instructions on this page for integrating Firebase with FlutterFlow.
If you enable the Require Authentication toggle, Firebase Authentication must be configured appropriately. Check out this page for setting up authentication.
Making an API call private
Change proxy settings
By default, when you test your API calls inside our builder, Run mode, and Test mode, we use a proxy to route your calls to avoid the CORS issue. However, if you want to use your proxy, you can disable these settings and provide your proxy URL.
To disable current proxy settings and provide your proxy URL:
Open the Advanced Settings tab.
Disable the Use Proxy for Test and/or Use Proxy for Run/Test Mode.
Enable the Use Custom Proxy URL.
Enter the Proxy Prefix URL (e.g. https://your-proxy-server.com).
Change proxy settings
Last modified 1mo ago