Create & Test API Call

In this guide, you'll learn how to create and test API calls in FlutterFlow. Integrating API calls allows your app to interact with external services, bringing in real-time data and functionality that enhances your app's capabilities.

Create API Call

To use an API in your app, you first need to create the API call in FlutterFlow.

Simply select API Calls from the left navigation menu, click the + Add button, and choose Create API Call. Enter an API Call Name, select the Method Type (GET, POST, DELETE, PUT, or PATCH), and input the API URL of the service you wish to access.

Method Types

The Method Type specifies the type of operation the API call will perform. Here’s a breakdown of common method types:

• GET: Retrieves data from the server.
• POST: Sends data to create or update a resource.
• DELETE: Removes a resource from the server.
• PUT: Updates or creates a resource with full data.
• PATCH: Partially updates a resource.

Dynamic API URLs

If you want to use a dynamic URL, for example, <https://reqres.in/api/users/2> where 2 is dynamic and <https://reqres.in/api/users?page=5> where 5 is dynamic:

1. Replace the hard-coded value with a meaningful name inside the brackets (e.g., from https://reqres.in/api/users/2to https://reqres.in/api/users/[user_id]).
2. And then, create a new variable with the same name you provided inside the brackets.

The further instructions are based on the Method Type you selected.

For GET & DELETE call

If you selected GET or DELETE as the method type, follow the steps below:

1. Optional: If the API call requires request headers such as an authorization token, add a header.
2. Optional: If the API call requires query parameters such as page number or user id, add query parameters.
3. Click Add Call to save the API Call.

warning

After making any changes, you must save the 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 a dynamic URL in a GET request is as follows:

To add such an API call:

1. Replace the hard-coded value with a meaningful name inside the brackets (e.g., from https://reqres.in/api/users/2to https://reqres.in/api/users/[user_id]).
2. And then, create a new variable with the same name you provided inside the brackets.

The DELETE API Call can also be defined similarly; just make sure you select the Method Type as DELETE.

For POST, PUT & PATCH call

If you have selected POST request, follow the steps below:

1. Optional: If the API call requires request headers such as an authorization token, add a header.
2. Create a request body for the API call.
3. Click Add Call to save the API Call.

warning

After making any changes, you must save the API call.

In this demo, a POST API call is defined with two variables, userName and userJob. The variables are used inside the JSON request body.

The PUT and PATCH API calls can be defined similarly; make sure you enter a valid API URL endpoint and select the correct Method Type.

Grouping API calls

You can create a group of API calls that share the same base URL. Grouping the API calls helps you add all request headers (e.g., auth token) at once, and they will be automatically added for all the API calls inside the group.

warning

For private APIs, headers defined within the group will not be automatically included. You'll need to manually add headers for APIs marked as private.

To create the API Group:

1. Click on the + button (top left side) and select the Create API Group.
2. Enter the API Group Name.
3. Enter the API Base URL. This should be the portion that is common in all the APIs. Note: Do not keep the '/' in the end.
4. You can add request headers by clicking on the + Add Header button. See detailed instructions on how to add headers.
5. Click Add Group. This will display the group on the left side.
6. Open the newly created API group, and click on the + Add API Call.
7. Add the API call as you would normally do. Note: Inside the API endpoint, enter the URL portion that starts after the base URL.

Import API definitions

We allow you to add multiple API call definitions by importing them directly from the Swagger/OpenAPI in bulk. With just a simple click, you can add a large number of APIs, significantly reducing the time and effort needed to create them manually.

Furthermore, the ability to import Swagger/OpenAPI definitions directly into FlutterFlow eliminates the risk of errors that may occur when creating API definitions manually, ensuring that applications are reliable and efficient.

info

We also add all settings that are required to run the API, such as headers, query parameters, variables, and body as they are defined in the Swagger file. However, you might need to replace the hard-coded values in Body text with the variables.

warning

Please note that while it is possible to import APIs created with OAS 2.0 in FlutterFlow, you might face some issues, such as the body request being lost during the import process. Our import functionality is built based on the OAS 3.0 standard, so for the best experience and compatibility, it is recommended to use APIs that adhere to OAS 3.0 or above.

To import API call definitions:

1. Click the Import OpenAPI icon. This opens the Import API Definitions dialog.
2. Drag and drop one Swagger or OpenAPI file onto the drop zone, or click Browse files and select the file. The file must be a .json, .yaml, or .yml file. The dialog accepts one file at a time.
3. If your project has no API calls or API groups yet and the file imports without warnings, FlutterFlow imports the APIs right away and closes the dialog. Otherwise, the Review API import dialog opens. Review the changes, and then click Import APIs (for a new group) or Apply updates (for an existing group).
4. After the import, the API calls appear as a group, named after the info.title value in the file. If the file has no title, add one to the file before you import it.

Here's an example of importing API calls in bulk, taken from here.

info

Save or discard any unsaved edits to your API calls before you import. The import doesn't start while edits are pending.

Review changes before you import

When you import a file into a project that already has API calls, the Review API import dialog shows what the import changes before anything is saved. Re-importing a file no longer replaces the group and discards your variables, response mappings, and settings.

At the top of the dialog, set the following:

• Import into: Select Create a new API group, or select Update followed by the name of an existing group. FlutterFlow preselects an existing group only when its name matches the title in the file.
• Import mode: Appears when you update an existing group.
  • Preserve configuration: Applies the changes you select and keeps your variables, response mappings, and settings.
  • Reset configuration: Replaces the group with the uploaded file and resets its configuration. This option isn't available if some endpoints in the file couldn't be imported.

Select Change file to upload a different file.

The left side of the dialog lists Group & shared changes and each API call in the file. Each API call is marked Added, Updated, or Removed, with a count of each at the top. Select Changes only to hide API calls that are unchanged. In Preserve configuration mode, use the toggle on an API call to include or skip its changes.

Select an item to see its details in three tabs:

• Configuration: Field-by-field changes to the URL, variables, headers, and other settings. Select or clear a change to include or skip it. If you edited a field in FlutterFlow and the file also changes it, the change is unchecked by default so that your edit is kept. Select it to apply the change from the file.
• Swagger source: A side-by-side comparison of the Previous Swagger and Uploaded Swagger definitions, including the schemas that the API call references. Changes to response schemas appear here for review, but FlutterFlow doesn't generate response mappings from them.
• After import: A preview of the configuration that FlutterFlow saves with your current selections.

If an API call is used in your app, the details show how many actions or queries use it.

Click Apply updates to save the changes you selected. If you removed API calls, FlutterFlow asks you to confirm. In Reset configuration mode, the button is Replace all, and FlutterFlow asks you to confirm that existing variable values, response mappings, shared headers, and API settings are reset.

If you skip changes that don't conflict with your edits, they appear again the next time you import the file.

info

If the file contains endpoints that can't be imported, the dialog shows a warning count. Select Show details to see which endpoints. While warnings exist, you can't remove API calls or reset the group, so a partial import never deletes your existing API calls.

info

If you import a file into a group that was created before this review existed, there's no previous definition to compare against. In that case, your edits and removals are kept unless you select them.

Testing API calls

You should always test your API call before using it inside your app. We make it easy for you to try the API call inside our builder.

To test the API call along with its response, follow the steps below:

1. Select an API call you have already created or are currently defining, and go to the Response & Test tab.
2. On the left side, you will see the Variables section, where you can enter the values for the variables defined for your API call.
3. On the right, the Preview section lets you check the API URL, request headers, request body, and response. In the Test Response tab, you can view the full API response, including both the JSON format and raw body text, as well as the response header.
4. 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 200), the result returned from that request will also be displayed below.
5. Any value of the JSON result can be accessed by defining the JSON path.

The demo below shows the testing of creating a new user using a POST request. The API Call takes two variables: userName and userJob. The successful POST request returns a status code of 201.

info

The testing of PUT and PATCH requests would also be similar to this.

API Call [Action]

Once the API calls are defined in your FlutterFlow project, you can use them wherever needed.

Open the Action Flow Editor on the widget where the API call should be triggered. After selecting the desired Action Trigger, search for "API Calls" in the Actions dropdown and select the API call you want to use.

tip

You can also add the API Call as a Backend Query that gets triggered automatically when the page or widget is loaded on the screen.

Go to your project and follow the steps below to define the Action to any widget.

1. Select the Widget (e.g., Button) on which you want to define the action.
2. Select Actions from the Properties panel (the right menu), and click Open. This will open an Action Flow Editor in a new popup window.
3. Click on the + Add Action.
4. On the right side, search and select the API Call (under Backend/Database) action.
   1. Select the Group or Call Name from the dropdown.
   2. Optional: If your API call requires variables (e.g., auth token, query parameters, user id, etc.), pass their value by clicking on the + Variable button.
   3. The Action Output Variable Name helps you retrieve the response of an API call. By default, we set it to any random name. However, you can change it to a meaningful name if you wish to. (e.g., loginResponse).
   4. You can add a conditional action that checks if the API call is succeeded.
   5. If the API call is succeeded, all actions under the TRUE path will be executed. For example, navigate to the home page if the login is successful.
   6. If the API call is failed, all actions under the FALSE path will be executed. For example, showing a snackbar if the login is unsuccessful.