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.
This article is part of a significant update to the Bubble manual and your feedback is critical to our efforts to continuously enhance our written documentation.
We would greatly appreciate if you could take a moment to let us know your thoughts on the quality of it. Thank you for your support!
Give feedback on this article
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.
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
The API Connector handles calls that come from your Bubble app to another application.
By pointing the API Connector to different URLs (Universal Resource Locator) you can access specific resources 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 HTTP request that includes a method 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 is a special plugin built by Bubble's development team that lets you connect to any service that exposes a JSON-based, RESTful web API. 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.
Our long-form video course gives you an introduction to how APIs work and how to use 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:
- 1.Navigate to the Plugins section of the Bubble editor and click Add plugin.
- 2.Search for API Connector
- 3.Click the Install button
Click the Install button to use the API Connector in your application.
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:
- 1.First set up the authentication for the API service
- 2.Secondly we set up the different call(s) we want to use
- 3.Then we initialize the call to make sure it works and to see the server's response
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.
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.
Giving your API a descriptive name makes it easier to organize the different providers.
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.
As we covered in our general guide on how APIs work, many API services will require authentication. This is the process of identifying who the client is in order to determine what resources it should have access to.
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 |
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:
- 1.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.
- 2.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.
- 3.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.
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, 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.
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.
To add a call, click the Add another call button
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.
The Use as dropdown lets you select whether to use that particular API call as a data source or an action:
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.
Setting the API call to be of type Data allows you to use the call as a data source. That way you can use it to populate Repeating Group for example.
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.
Setting an API call to type Action lets you run that call from a workflow in your application. The label (RentalSoftware - Create Unit) is a combination of the name you gave the API provider and the name of the call in the API Connector.
When a call is made to a specific resource, we need to specify an HTTP method 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.
Setting the HTTP method in the dropdown in red tells the external app what kind of action you want to take. GET usually means you want to return data.
In our general article on APIs we explored how a RESTful API call uses a URL to identify a specific resource.
For example, when we were looking at Bubble’s Data API (used to give external systems access to the database) and Workflow API (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.
In the example above, we have found the correct endpoint to translate a text using the Google Cloud Translation API. The documentation also
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.
To have a closer look at how the API Connector works in practice, you can check out our guide on how to connect to Google Cloud to utilize the Cloud Translation API.
Article: Case: Connecting to Google Translate with the API Connector
Last modified 4mo ago