Comment on page
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. Depending on the API's definition, you may utilize some or all of these concepts to successfully implement the API call in your project.
Here are they:
​Headers​
​Query Parameters​
​Variables​
​Body​
​JSON Path​
​JSON to/from Data Type​
⚫ 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 returns.
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:
1.Select the Headers tab and click on the + Add Header button.
2.Inside the input box, enter the header name followed by the 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:
1.Select the Headers tab and click on the + Add Header button.
2.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 want 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 an app state variable (with Persisted -> True). Check the visuals below:
​
​
​
Now you can pass the dynamic token:
1.Select the Headers tab and click on the + Add Header button.
2.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]).
3.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 app state variable to the API call.
Now from the API call (that requires an authentication token), pass the token value from the app state variable.
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:
1.Ensure you have added the API call action and provided the Action Output Variable Name.
2.Now, whenever/wherever the Value Source is set to From Variable, select the Action Outputs > [Action Output Variable Name] (e.g., Action Outputs > loginResponse).
3.Set the API Response Options to Get Response Header.
4.Enter the Header Name. Note that this must match the name of the response header from your API call.
5.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:
1.Select the Query Parameters tab and click the + Add Query Parameter button.
2.Enter the Name of the query parameter. 
3.Set the Value Source to Specific Value or From Variable.
1.If you want to pass this value from your page, app 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.
2.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
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:
1.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]).
2.Select the Variables tab and create a new variable with the same name you provided inside the brackets.
⚫ Variables
Variables allow you to pass the dynamic values from your page, app 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 an app state variable to the request header of an API call
Passing a username and password from TextField widgets 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, app state variable, or any other source.
Passing values to variables
⚫ Body
You can send data (as a 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 in the following formats:
1. JSON format
To create a request body in JSON format:
1.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).
2.Select the Body tab and set the Body dropdown to JSON.
3.Copy-paste your request body and replace the values with the variables by dragging and dropping them inside your JSON body.
2. 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.
3. x-www-urlencoded format
To create a request body in x-www-form-urlencoded format:
1.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).
2.Select the Body tab and set the Body dropdown to x-www-form-urlencoded.
3.Click on the + Add Parameter and enter the Name of the parameter. 
4.Set the Value Source to Specific Value or From Variable.
1.If you want to pass this value from your page, app 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.
2.If you want to pass a static/fixed value, select the Specific Value, set its Type, and enter its Value.
4. 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 Uploaded File. This will allow you to pass the file stored locally on the device using an action such as Upload/Save Media.
⚫ 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]"
]
Important: JSON keys must start with a letter, an underscore, or a dollar sign. They cannot begin with a numeric character. However, in cases where you have keys with numeric prefixes, such as $.0_image, you can access them using bracket notation, like this: $.["0_image"].
Learn more about JSONPath and how to define a proper expression from this page.
Adding JSON Path
To add JSON path:
1.First, create and test your API call.
2.Inside the JSON Paths section, click on the + Add JSON Path.
3.Enter your JSON Path and give it a Name.
4.If you entered the valid expression, you'll see the starting part of the response under the Response Preview column. To see the complete response, click on the Preview icon.
5.If the returned response is a list of items, by default, Is List will be checked; however, if you want to convert the response into the list explicitly, checkmark it.
6.We also recommend all the possible JSON paths (under the Recommended tab) that might include what you are looking for.
1.To add the recommended JSON path, checkmark the Selected, open the Selected tab, and give it a name.
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:
1.Select your API response.
2.Set the API response Options to JSON Body.
3.Set the Available Options to JSON Path.
4.Set the JSON Path Name to the one that you created earlier.
⚫ JSON to/from Data Type
JSON to/from Data Type is often referred to as JSON deserialization and serialization. It allows you to convert JSON data from an API response into a custom Data Type when you receive it. Also, it enables you to convert your custom Data Type back into JSON when sending data in an API request.
This is a more robust and maintainable way to work with JSON data in your app. It reduces complexity and potential errors (e.g., typos) compared to manually navigating JSON paths.
Create custom Data Type matching to JSON structure
First, create a Data Type with the same structure as your API response. Here's what the sample JSON response looks like after mapping it into a custom Data Type.
Creating custom data type as per the JSON response
After this, you can choose to convert to or from the Data Type based on your requirements.
JSON to Data Type
Let's see how to get the JSON into the custom Data Type using an example that fetches the list of products from this API. Here's how it looks:
Displaying a list of products
Here's how you do it:
1.First, ensure that you create a custom data type that matches your JSON structure.
2.On ListView, after adding the API call backend query, access the values by setting the following options.
1.Generate Children from Variable by setting API Response Options to JSON Body.
2.Set Available Options to To Data Type because we want to convert the whole JSON response into our custom data type.
3.Select the Data Type that you want to convert into. For this example, it's 'AllProducts'.
4.Set Available Options to Data Structure Field because we want to grab only a specific portion from the JSON, which has a list of products and not other items such as 'total' and 'skip'.
5.Select Field to the field that holds the list of products, i.e., 'products' for this example.
6.Click Confirm twice.
3.Now, you can bind data in UI elements as you would normally do by setting the Available Options to Data Structure Field and Select Field that you want to display.
JSON from Data Type
Sometimes you might want to dynamically create a JSON body and pass it along the API request instead of manually configuring each field in the API call editor. You can do so by adding data into a custom Data Type and then converting it into JSON while making an API call.
Let's see an example of adding a product by sending its data in JSON format in the API request.
Add product
Here's how you do it:
1.First, create a custom data type that matches the JSON format of the API request body. Here's how it looks for this example.
Custom data type matching to JSON structure
2.In your API call, create a variable with type JSON and put it inside the Body section.
3.On click of Add button, we'll store values from UI into the page state variable of custom data type. Then, while making an API call, pass that page state variable and set the Available Options to To JSON.
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:
1.Open the Advanced Settings tab.
2.Disable the Use Proxy for Test and/or Use Proxy for Run/Test Mode.
3.Enable the Use Custom Proxy URL.
4.Enter the Proxy Prefix URL (e.g., https://your-proxy-server.com).
Change proxy settings
Cache API Results
You can enable this option for a specific API call. So when your app runs, multiple calls to this endpoint with the same arguments will be cached. Learn more about caching here.
Decode Responses as UTF-8
Enabling this option ensures that the data you get from a server or website is read as UTF-8, a common way of storing text. Usually, a server or website tells you how to read its data, but sometimes it doesn't. This option makes sure you read the data in UTF-8 way even if the website doesn't tell you to do so.
Last Updated Date: November 1, 2023
Data and Backend - Previous
API Calls
Create & Test API Call
Last modified 1mo ago