API Connector
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.'
To learn more, we put together a video tutorial on how to use the Etsy API and another that shows how to create a Body Mass Index calculator.
Note: API Connecter calls are by default sent from the Bubble server (for non-dedicated Bubble apps) and thus susceptible to 3rd party API rate limiting since the rate limit is shared across all Bubble apps. Consider sending the call from the browser, when appropriate, if rate limiting is a concern.
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.
Depending on the operation chosen, a token is generated and added to calls to authenticate them. See here for details on each option.
This deletes the API call.
Warning: This is permanent and cannot be undone.
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.
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.
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).
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.
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 private Headers or 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.
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 callDefault 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
The API Connector currently does not support non-utf8 encodings.
All API calls return bytes of data, which must be interpreted by clients like Bubble servers or your internet browser. The oldest, and most popular encoding standard, is called ASCII, for easily translating these bytes into text characters. As a part of this standard, the most widespread encoding format for special characters is 'UTF-8'. Because 'UTF-8' is so widely adopted, Bubble does not support any other text encodings.
Note: When using the API Connector or App Connector, parameters currently cannot be a 'raw' list of Bubble Things, e.g. a dynamic statement that results in a List of Things. This is because a raw list of Bubble Things is not rendered in the kind of text formatting that API endpoints expect. One workaround for this is to use the ":join with" operator on the list of Bubble Things to turn it into a format accepted by the API endpoint (this is likely a format like ["first thing", "second thing"]).
