The API Connector allows you to connect to almost any external API from Bubble. It expects a correctly formatted JSON body as a response. You can supply headers, parameters, and a call body. The API calls created can be used as actions or consumed as data. When used as data, they appear in the dropdown menu for "Get data from an external API" when "Insert dynamic data" is clicked. When used as actions, they appear in the Plugins section of the Actions dropdown menu.
Once you configure an API call, you need to initialize it. If you don't, it will not appear in the Bubble Editor. Please note that initializing a call actually runs/executes it. If a call deletes an item or creates an item that requires a unique id, the Initialize call button will, if successful, delete or create the item. Thus, the next call will likely fail since the item already exists or was deleted. To initialize an API call with mandatory parameters and no sensible default, you can set a default as an example, click to “Initialize,” then unset the default.
An API call's URL is never sent to the user's browser. Call headers and parameters are only sent to the user's browser if you mark them as 'client safe.' Parameters, such as a secret API key or password, should never be marked as client safe. If you mark a parameter as client safe, you will be able to assign it dynamically in the Bubble Editor. A search term in a search query is a good example of a client-safe parameter. The call's body is sent to the user, thus it is not client safe. When you post a JSON body, you must create a header with key 'Content-Type' and value 'application/json.'
Choose a name for this call. It must be unique because no two API calls can have the same name.
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.
This deletes the API call.
This is the HTTP verb. The most common are GET, POST, PUT, PATCH, and DELETE.
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.
This is the call's body. It is client safe, meaning values are sent to the user's browser when the call is made.
Click to add and configure a new HTTP header. Headers are not sent to the client by default, but they will be if you enable the Client-safe checkbox.
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. This is an advanced feature.
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.
Check this box to prevent a parameter default value used for initialization from being sent to the client or workflow inputs.
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).
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.
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.
Important: You must initialize every call before using it in Bubble. If you do not, the call will not appear in the list of available calls. Initializing the call actually executes it and allows you to decide what data will be available in Bubble and its type. 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.
The API Connector is a special plugin but can be found in the plugin gallery from the Plugins tab like any other plugin.
Once installed on your app, the plugin then requires further configuration for each API and each call desired. The API Connector can handle as many APIs and calls per API as needed.
- Most API providers have documentation for their API, including on the topic of authentication, which can be tricky
- The API provider's documentation may show you "cURL commands" as examples of the various calls (these can be identified if you see code that starts with the command
curl). The API Connector has a feature to import cURL commands, so you can copy and paste from the documentation to get a big head start on setting up a particular call
- 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.
- Stuck? Try asking the forum for help or seeing if there is a post from somebody else about that API provider