The API Connector

The API Connector allows you to set up connections to external APIs from your Bubble application.

Introduction

The API Connector is a Bubble-developed plugin that lets you connect to almost any external API from your Bubble application. You can set up headers, parameters and a call, and each call can be set up to be used as an action in your app or asa a data source.

Response format

The API Connector expects a correctly formatted JSON body as a response.

How calls are sent

API Calls made with the API Connector are routed through Bubble's server unless specifically set not to do so (see article below).

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: 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.

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.

Note that even though by default, API calls are made from the server, a description of the call is sent to the browser and are thus visible to a savvy user. This means that any sensitive parts of the call, especially secrets / tokens, should be in fields marked "Private".

Installing the API Connector

The API Connector can be found in the plugin gallery from the Plugins tab like any other plugin. You can find it quickly by searching for the string API Connector.

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.

FAQ

How do I know how to authenticate and set up calls?

Most API providers have documentation available online that gives you the technical details needed to authenticate and set up the call correctly. Still, setting up API connections can in some cases be among the more technically challenging parts of Bubble development.

Our introductory article on APIs can serve as a starting point to learn how APIs work in general. You may also be interested in checking our long-form article on How to use the API Connector and you can check out our example case where we set up a connection with Google Cloud.

Lastly, you may find it easier to set up and test a call in a service like Postman before setting it up in Bubble. You can export a successful call from Postman as a cURL command and import it into the API Connector.

• 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

Things to note

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"]).