Adding calls

After authentication is set up, you can add as many calls as you need to the API provider.

Experience level

This core reference entry is suited for advanced-level builders.

In-depth articles (5)

To learn about this topic more in-depth, we recommend reading the suggested articles below:

The API Connector

• Article: API Connector authentication methods

• Article series: The API Connector

  • Article: Authentication

  • Article: API Connector security

---

Cases

• Article: Case: Connecting to OpenAI/ChatGPT

• Article: Case: Connecting with Google Translate

---

APIs

• Article series: APIs This article series covers how APIs work in general, and the different steps that take place when two computer systems communicate.

Videos (2)

• Intro to APIs & the API Connector | Bubble Crash-Course

• Bubble Webinar 2 - The API Connector

• How to Setup Google API Keys

Call name

Choose a name for this call. It must be unique because no two API calls can have the same name.

Use as

Select from Data or Action to determine how this call will be used in Bubble. Data calls appear in the 'Get data from an external API' dropdown menu and Action calls appear in the Plugins section of the Actions dropdown menu.

Delete call

This deletes the API call.

Warning: Deleting an API call is permanent and cannot be undone.

Method

This is the HTTP verb. The most common are GET, POST, PUT, PATCH, and DELETE.

URL

This is the call's URL. It is not client safe, meaning the value is not sent to the user's browser when the call is made.

Body

This is the call's body. It is client safe, meaning values are sent to the user's browser when the call is made.

Headers

Click to add and configure a new HTTP header to this specific call. Check the Private box to stop the information in the header to be visible client-side. Check the Optional box to set up this specific key to be optional.

Body type

Select here the body type of the request. Most requests will send a JSON body, but for more advanced usage (such as uploading a file), you can use a Form-data or Raw body.

Note: If you are using a Raw (plain text) body, be sure to include a 'Content-Type' header that specifies the format you are using so that it can be parsed properly by the API you are calling.

Parameters

Click to add and configure a new call parameter. Parameters are not sent to the client by default, but they will be if you enable the Client-safe checkbox.

Default values for an API connector call (or plugin) behave differently if they are optional or mandatory. Optional default values are placeholders that aren't passed to a call unless they're changed to something else in the app. Mandatory default values are actual default values.

Allow blank

Check this box to prevent a parameter default value used for initialization from being sent to the client or workflow inputs.

Default values for an API connector call behave differently if they are optional or mandatory. Optional default values are placeholders that aren't passed to a call unless they're changed to something else in the app. Mandatory default values are actual default values.

Include errors in response & allow workflow actions to continue

Check this box to handle API call response errors yourself. When this box is checked, Bubble will allow workflows or actions to continue when an api call error is returned and expose the error object for use in a dynamic expression. There are 4 parameters that are available as a part of the error object: error's status code (number), error's status message (text), error's body (text), and error's has returned error (yes/no).

Note: If you check or un-check this option after initializing the call, you will need to re-initialize as this option changes the format of the response.

Capture response headers

When the parameters are detected from an initialization request, you can include the request headers in the detected data if some important data is in them.

Allow call to run directly in the browser where applicable

Check this box to allow this API call to run directly from the browser, rather than Bubble's server.

This option will only available in certain situations. More specifically, this option is only available for public API calls (Authentication is set to None) with no Headers or private Parameters. In addition, the call must be used as a data call. Support for Use as Action is coming soon.

The biggest benefit of using this option, on top of performance, is that your API call will not count against API call quotas across all of Bubble, lessening the risk of accidental rate limiting by a 3rd party API.

Note: Due to the nature of this type of client-side (from the browser) API call, it will only be sent from the browser if it doesn't require interaction with the server. For example, using the API call response as a data source.

If this option is selected, but the API call is included in a workflow that involves the server (i.e. making changes to a Data type), the API will revert to being sent from the server.

Whenever an API call is made from the browser, information related to that call can be intercepted on the client side. That means you should be cautious exposing sensitive information (e.g. API keys) in these calls. If you are unsure of the potential risk of sending data to the browser we recommend not activating this setting.

Initialize call

When initializing a call, you should use only sample or non-sensitive data in the parameters. Any data entered during this step becomes part of the API schema, which is included in your app’s source code and could potentially be accessed by others.

Every call needs to be initialized before it can be used in your app. Initialization is done for two reasons:

• To confirm that the call was successful

• Bubble uses the response to recognize the data being returned by the server

Take caution when utilizing initialization API calls as they may produce actual outcomes, including the modification of live data. Be mindful of what kind of results the initial call may produce prior to executing it.

To initialize an API call with mandatory parameters and no obvious default, you can set a default as an example, click to “Initialize,” then unset the default or select Allow blank.