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.
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 request will send a JSON body, but for more advanced usage (such as uploading a file), you can use a Form-data 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.
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.
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.
The API Connector currently only supports JSON and form-data format in the body, i.e. not formats like plain text, XML, etc.
The API Connector currently does not support most special characters (i.e. it does not support non-utf8 encodings).
Known Issue
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"]).
