The API Connector
This section covers Bubble's API Connector. The API Connector is used to make outgoing connections to external applications and use it as a data source or trigger actions.
In the Bubble API section we covered API requests that are incoming – they are initiated by an outside system and Bubble takes some kind of action based on their credentials, endpoint and parameters.
This is our in-depth manual article on the API Connector. If you are familiar with APIs and want the shorter technical reference go to the API Connector reference entry. We also have a dedicated article covering API Connector security.
In this section we’ll look at requests that are outgoing – when your Bubble app sends a request to an external system. When you use the API Connector, your Bubble app is the client and the API service is the server.
You can read more about the client/server relationship in our Introduction to APIs. Article section: The client/server relationship
By pointing the API Connector to different URLs (Universal Resource Locator) you can access specific that the API provider offers.
Just like incoming requests these calls can ask for some data to be returned or for an action to be performed.
Structurally, you’ll recognize what they look like: they also use an that includes a like GET, POST, PATCH and DELETE.
Bubble's plugin store offers thousands of plugins both made by Bubble and the community. Many plugins let you connect to well-known API services quickly and effortlessly without having to set it up in the API Connector. Link: Plugin store Article: Plugins that connect to APIs
The API Connector
The API Connector is a special plugin built by Bubble's development team that lets you connect to any service that exposes a , . You can use this to add API calls to fetch data from an external service, or post data to trigger some actions on the service's end.
Installing the API Connector
The API Connector is a plugin created by Bubble and needs to be installed in your application before it can be used.
To install the plugin:
Navigate to the Plugins section of the Bubble editor and click Add plugin.
Search for API Connector
Click the Install button
External API documentation
Every API service is different and to make it possible to connect successfully to their platform, most providers offer API documentation. Using the external documentation is critical to understand how to authenticate and make calls to that specific service, so we recommend you get to know it before you start.
If this is your first time working with APIs, the documentation may seem fairly technical at first, but you’ll find that with the RESTful API style most providers follow a similar standard.
Most APIs will go through three steps before they can be used:
First set up the for the API service
Secondly we set up the different (s) we want to use
Then we the call to make sure it works and to see the server's response
Test accounts
Many API providers such as Stripe offer a demo account that you can use to test your API calls without making any actual changes (or payments in the case of Stripe). Check whether the service you want to connect to offers this kind of testing environment to be able to properly test all your calls with no risk.
Naming API providers
The first part of setting up a new API request is to give the service a name. This will typically be a descriptive name (often the same as the provider’s name) such as Stripe, Google Cloud and OpenWeatherAPI.
The name is used around the Bubble editor to organize the different calls that we’ll add later. It’s therefore a good idea to use a name that makes the relevant call easy to find later.
The API name becomes part of your application’s client-side code and should not contain any sensitive information.
Authentication
As we covered in our general guide on how APIs work, many API services will require . This is the process of identifying who the client is in order to determine what resources it should have access to.
Authentication methods
There are many different ways to authenticate. Most API providers will have documentation available online that specifies their authentication method and many require you to generate a unique API token.
The list below represents the most common authentication types. You can read more about each type in the article below: Article: Authenticating with the API Connector
Method | Description |
None or self-handled | No authentication required |
Private key in URL | The private key is included as a parameter in the URL |
Private key in header | The private key is included as an HTTP header in the request |
HTTP Basic Auth | The client sends username and password in plain text |
OAuth2 Password Flow | The client sends username and password and receives an access token in return |
OAuth2 User-Agent Flow | Similar to OAuth2 Password Flow, but for user-agents |
OAuth2 Custom Token | The client sends a custom token to the server for verification |
JSON Web Token (JWT) | The client sends a JSON web token to the server for verification |
Client-side SSL certificate | The client presents a SSL certificate to the server for verification |
API tokens and security
We recommend learning how to set up the API Connector in a secure way. If you want to learn more about this, check out our dedicated article on API Connector security.
Article: API Connector security
If you are new to APIs it’s important to emphasize here the importance of keeping your API token secret. API tokens in principle serve the same function as a username and password, but they add security and flexibility that is useful to an API provider:
They can be easily generated and revoked: Unlike a username and password, which are typically created and managed by an actual person, API tokens can be easily generated and revoked by the API provider. This makes it easy to control access to the API and limit the impact of any security breaches.
They are more secure: API tokens are generally more secure than username and password combinations, because they are typically harder to guess or brute force. They can also be rotated regularly to further improve security.
They are more convenient: API tokens are generally easier for developers to work with than username and password combinations, because they do not require any special handling. This can make it easier for developers to use your API and can increase adoption of your API.
Just like a username and password, a token is only as secure as the one who manages it. Tokens to important services like Stripe should be handled with the utmost confidentiality.
API keys/tokens should never be stored in Option Sets or in on-page elements and/or workflows, since that makes them visible in your application’s client-side source code.
Shared headers
Sometimes you'll need to add the same header to all your calls. This can be related to authentication, but it doesn't have to be. Another typical key and value included in the header section is the content-type, which specifies the expected format of the call.
Consult the external API documentation to see if they require any specific headers.
Shared parameters
Shared parameters, like the headers described above, will be added to each and every call in the relevant API. Shared parameters are added to the body of the request rather than the header.
It doesn't make any technical difference whether you add headers and parameters directly to each call or use the Shared headers/parameters feature. Adding them to this section will simply save you some time and make the headers and parameters easier to set up and manage.
Adding calls
Now that we have 1) given our API service a descriptive name and 2) authenticated as a client (if necessary) it’s time to add the actual calls.
Again we need to name the call before doing anything else. Give it a descriptive name that can be combined with the name you gave earlier to the API provider. For example, you might name the API Provider Stripe and the API Call Create payment.
Secondly, we need to tell Bubble what this call will be used for in the Use as dropdown.
Use as
The Use as dropdown lets you select whether to use that particular API call as a data source or an action:
Data
Use as data means that Bubble will treat the API call as a data source. Use this for calls that you set up to retrieve data that you want to display in your app. You will find API data sources in the Get data from external API in the dropdown list of data sources.
Action
Use as action makes the API call available as an action in your Workflow editor. You will find API action calls in the workflow editor under Plugins.
The HTTP method
When a call is made to a specific , we need to specify an that tells the server what kind of action we want to initiate. The five most used HTTP methods are:
Action | Description |
GET | Retrieve data |
POST | Create data |
PUT | Update data |
PATCH | Replace data |
DELETE | Delete data |
HTTP methods are sometimes called HTTP verbs. Generally they are used as illustrated in the table above, but to find the correct HTTP method for the resource you want to access, check the API providers documentation.
The URL and endpoint
In our general article on APIs we explored how a call uses a URL to identify a specific resource.
For example, when we were looking at Bubble’s (used to give external systems access to the database) and (used to give external systems access to workflows) we looked at how Bubble generates a unique URL for each data type you choose to expose in the Data API and each API Workflow you choose to expose in the backend workflow editor.
External RESTful APIs work in the same way: you direct your Bubble application to a specific URL in order to reach the resource that you want. Together, the HTTP method and the endpoint form a unique API endpoint that defines the specific action that is being requested.
For example, a GET request to a "/users" endpoint might be used to retrieve a list of users from an API, while a POST request to the "/users" endpoint might be used to create a new user.
Finding the correct endpoint
The endpoint is the combination of the HTTP method and the URL (resource locator). What method to use and what the URL is differs between different API services, and you can usually find the correct endpoint by consulting the documentation of the API provider.
Initializing a call
When you initialize a call, keep in mind that Bubble sends an actual call to the server, potentially loading and manipulating data.
The test data that you enter in the value field of a parameter, is visible in your app's code unless the Private box is ticked. You should remove any sensitive data from this field before you deploy.
When a call is set up, it needs to be initialized. This means to run the call to test it. This is a required step before the call can be used in your app, for a few reasons:
It informs us about the success or failure of the call.
It furnishes us with a response that outlines the JSON data format. This enables Bubble to establish the call as a data source, as it understands its organization.
You can also have a look at the data (structured or raw) that the server returns, to verify that it gives the expected results, and to understand its structure
When you click the Initialize a call button, Bubble sends the call to the server, and displays the response in a popup. If the call is unsuccessful, the API Connector will show you the relevant error message.
Raw body text
Raw body text is an experimental feature. Currently, it is only accessible via the API connector when the include errors or include headers checkbox is clicked.
Also, it is not available if you use a nested field in a dynamic expressions, such as first items's raw body text.
You can also view the raw body text returned by the server. This refers to the unprocessed information received from the API endpoint.
Raw data provides the foundational information that can then be parsed, manipulated, or displayed as needed within your app. It forms the basis for further processing and integration within the app's actions and data sources.
Last updated
