Introduction
The Bubble API is organized around REST and uses HTTP response codes to indicate API errors. JSON is returned by all API responses, including errors. The generic endpoint is going to be
https://appname.bubbleapps.io/api/1.1/sub_path
or
https://yourdomain.com/api/1.1/sub_path
A few sample endpoints:
POST https://appname.bubbleapps.io/api/1.1/wf/my_endpoint for Live
POST https://appname.bubbleapps.io/version-test/api/1.1/wf/my_endpoint for Development
GET https://appname.bubbleapps.io/api/1.1/obj/myendpoint for Live
GET https://appname.bubbleapps.io/version-test/api/1.1/obj/myendpoint for Development (note the difference in endpoint convention for the Workflow vs Data APIs).
Note that if the site is setup to work on HTTPS, use this protocol.
As the app has two versions, Development and Live, the API will have two versions as well. If you add /version-test/ after the appname or domain name, you can access the Development version of the API.
https://appname.bubbleapps.io/version-test/api/1.1/sub_path for Development
https://appname.bubbleapps.io/api/1.1/sub_path for Live
There are several ways to authenticate when making a call to the Bubble app's API, depending on the situation:
– Use an API Token generated in the API section in the Settings Tab. This API Token is secret and should not be shared with anyone. To authenticate with such a mechanism, add Authorization: Bearer API_TOKEN to the header. When you authenticate with such an API Token, the call is run in the context of an admin user of the app, who has access to all data.
– Create Sign up/Login API workflows. This is useful for building an alternative front-end to the Bubble app, such as a native app that you developed. When an API workflow contains a sign up or login action, then a user ID, token, and expiration, expressed in seconds, are returned with the response of the call. Subsequent calls to the app's API, with a header Authorization: Bearer API_TOKEN, runs all calls and workflows in the context of the user associated with the token. This user will be the 'Current user,' who you can access with actions. Privacy rules will apply to this user as they would if the user was logging in the Bubble app and using it in their own browser. This token should be kept safe.
- Session cookie. If the call is done from the browser and there is a session cookies present, the user represented by the cookie will be the call will be run in the context of this user.
– No authentication. In some cases, you may want to enable calls that aren't authenticated, e.g., to let a user sign up or login to the app. To enable this, check the box 'This endpoint can be run without authentication' at the endpoint level. When a workflow is run under such circumstances, the privacy rules that apply are the one for 'everyone.'
You can also add your API Token directly in the URL for both the Workflow and the Data API as a querystring parameter api_token. This approach is not recommended as it is less secure.
The Bubble API returns data as JSON. If you're using the Workflow API, you can define which data the call returns through the 'Return data from API' action. When your workflow uses a 'Sign up' or a 'Log the user in' action, the response will contain a user_id, token, and expires value that allow you to authenticate subsequent calls as the user who just signed up/logged in. Successful calls return a 200 code and possibly some data, while failed calls return an error code.
Frequently, you want to send data/parameters with the calls. They can either be in the URL in a stringified, URL-encoded way, usually for GET, or in the body of the request, usually for POST. When you send data with a request, Bubble validates it and makes sure it has the correct format. Here are four particular cases:
1) Geographic addresses: This data should be sent as a string '33 Nassau Avenue, Brooklyn, NY 11222,' and Bubble will use the Google Map API to encode it as an address with a latitude and longitude. You can also send them as an object.
{
address: String
lat: Number
lng: Number
}
where latitude and longitude or address is mandatory.
2) Dates: Send a date as a string or timestamp. For example, 'Wed Jan 13 2016,' '01/13/2016,' 'Wed Jan 13 2016 16:45:09 GMT-0500 (EST),' or '1453398788637.'
3) Files and Images: When a parameter is a file or image, you have two ways to define the content in the request. You can submit a string, which should be the URL of the file/image hosted on a storage service, or you can provide the raw data and the API call will upload the content to Bubble's hosting services. In the later case, the value provided should be a JSON object as follows:
{
filename: String
contents: Base64-encoded binary data
private: Boolean
attach_to: String
}
where:
– filename is the file name. Optional, but recommended to get the file type.
– contents is the base64-encoded binary data of the file. Required.
– private is a boolean, true/false, that defines whether the file is protected and attached to an object in the database. Optional.
– attach_to is the unique ID of who/which thing owns the file. Required if private is true.
If there is an ambiguity in processing the data sent, Bubble returns a 400 error, 'INVALID_DATA.'
4) Things: If a parameter is a thing, e.g., an entry in the application database, or a list of things, you can send it using the ID of the thing. When such a request is made, the API will retrieve the thing with that ID and validate the type. It should be the type defined at the parameter level for a workflow, for instance. If a thing isn't found or not of the right type, Bubble returns a 400 error, 'INVALID_DATA'.
The Bubble API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error resulted from the provided information, and codes in the 5xx range indicate an error with Bubble's servers.
Common errors include:
– 400 Bad Request This usually happens when the data sent with the call doesn't match the expected format.
– 401 Unauthorized This happens when the authentication isn't correct. Either the API Token is wrong, the user token doesn't exist, or you provided a key when the call shouldn't be authenticated.
– 404 Not found This usually happens when the endpoint doesn't exist, isn't a published public endpoint, or when the Bubble app doesn't expose an API at all, as defined in the API section in the Settings Tab.
Requests are rate-limited by default to 1,000 requests/minute per application and version (live / development). A rate-limited request will return an HTTP 429 error. On the Professional plan and above, you can add capacity units to get more. Each unit above 2 capacity units is an additional 1,000 API calls/minute/unit. This limit can be customized on Dedicated Plans.
A new version is introduced when a non backward compatible change is deployed. The current API version of 1.1 was introduced on January 19, 2017.
– Version 1.1: Values are returned as Javascript objects when possible in API responses. In particular, dates are returned as 2016-11-11T19:14:46.517Z instead of a timestamp, and geographic addresses are returned as a JSON object. Introduced on January 19, 2017.
location = {
address: "Les Ferreys, 14130, France"
lat: 49.19959
lng: 0.19707
}
– Version 1.0: The first release. Introduced in January 2016.
You can send values for addresses either as an address string or object, which should be similar to the output format. When submitting, only lat/lng or an address is required.
Bubble exposes a dynamic Swagger Specification (version 2.0) that you can use to expose the structure of your API. It can be used with other programming tools, or with documentation generator, etc. You can read more about this here.
You can find the Swagger Specification as JSON at this endpoint:
https://appname.bubbleapps.io/api/1.1/meta/swagger.json
or
https://yourdomain.com/api/1.1/meta/swagger.json
