Defining the API
The Bubble API is currently accessible to users on a Personal plan and above. To activate the API, go to the API section of the Settings Tab and check the relevant checkboxes.
You expose your application's data to the outside world by picking the types you expose via the API. You can pick these fields by checking the relevant checkboxes in the API section of the Settings Tab. Note that there is no interface for the Data API after it is activated. Rather, there are specific endpoints that become available with each type that is exposed.
Important: as soon as you expose a data type, external services and developers will be able to access your data, even without visiting your application. You should set up your privacy rules carefully to ensure that only authorized developers (that get an API key from you, for instance), will have access to the right data.
You can access the API part of your app at the bottom of the Application Menu - "Backend Workflows". This will take you to a special 'page' with a few different kinds of workflows that do not belong to any particular page. The Design tab will not be accessible, and the entire work will be done in the Workflow tab.
Creating API workflows is quite similar to creating normal workflows in your page, with a few differences. Each API workflow corresponds to an "endpoint" that can be called via the Workflow API.
Each API workflow should have a unique name. The name should be lower case and without spaces, as it will be used in the URL of the request to the API.
Actions that can be used in an API workflow are server-side only actions.
You can pick a few options regarding authentication and exposing the API workflow to the outside world.
- 1.Expose as a public API workflow: check this box if you want to use this API workflow from another service (such as Stripe), or let other developers call its endpoint. If you're setting up a workflow just for scheduled operations inside your app, this box shouldn't be checked.
- 2.This workflow can be run without authentication: an API workflow is usually run with an API key when triggered by an external service. Check this box if you do not require the request to have an API key. This is particularly useful when you're enabling your users to sign up or login to your app.
- 3.Ignore privacy rules when running the workflow: an API workflow is run based on the token/key that it is sent with. All privacy rules will apply accordingly. However, sometimes, you may want the workflow to bypass these rules, even if run without authentication, and be run as an admin user that has all rights to the data. Check this box if so. As always with security and privacy options, use this feature with caution.
An API workflow can take some parameters. This is the way you define which data can be sent to the workflow when making a request (or scheduling a workflow in the future). You have two ways to define parameters. You can either define the structure yourself, or automatically detect the structure of the received data. The first option is better for an API workflow you define and when you control how the request is made (for instance when you use scheduled workflows, or build a custom client), while the second option is useful when using the API workflow's endpoint as a response to a webhook.
One you have defined parameters in the API workflow's definition, you will be able to access this data in the subsequent actions. The parameters you have defined will be at the top of the first menu of the Expression Composer. The type of data you have defined will impact the different options you can find in the following dropdown menus.
When you add a parameter, you should name the parameter, pick a type of data, and specify whether the parameter is optional or not. The type of data is very important, as Bubble will validate the data when a request is made, and will return an error if a parameter is invalid. See below more details about how to make a request.
You also have the option to automatically detect the structure of the data that is sent by an external service (webhook). To do this, you can click the button Detect data and trigger a request to the API workflow's endpoint.
Note that for the initialization to be effective, the request should be made to the API workflow's endpoint URL, plus initialize at the end. The endpoint will look like
The request should be made to the test version of your app, as it's the version you're modifying.
Once the data has been detected, you'll be able to pick the fields that you want, and choose the type of this data to use the parameters in the subsequent actions.
Most API Workflows will run some actions, but under some circumstances, you may want to return some data. For instance, if an API workflow creates a thing, you will want to return the raw thing, so that the result can be displayed or saved. To return data, you can use a 'Return data from API' action. This action is specific to the API Workflow, and cannot be found in general workflows.
To add OAuth credentials to your application navigate to your Settings tab.
From there you will get two keys, one for Client ID and another for Client Secret. Keep these keys private!
You then need to add a Name and a Redirect_uri:
- The Name is the application you are allowing access your app.
- The Redirect_uri is for the URL you want to send users to after they have successfully connected to this app.
The Swagger Specification is a standard way to describe an API. It can be used to generate a documentation, or to let other tools integrate with the API. Bubble provides a Swagger Specification out-of-the-box when you activate the API for your application. To get it you can hit the endpoint