Defining the API

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

  1. The POST/Workflow API lets you access a new page in your app that lets you edit workflows that can be triggered by another service, or that can be used for scheduling purposes. If you need to schedule some workflows in the future in your app, or run a workflow on a weekly or monthly basis, the Workflow API is the right tool for this.
  2. The GET/Data API is the way you expose data to the outside world.

Setting up the GET/DATA API

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.

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. See the Authentication section for more information about API Key, authentication and rights.

Setting up API Workflows

You can access the API part of your app at the bottom of the application menu. This will take you a special 'page'. The Design Tab will not be accessible, and the entire work will be done in the Workflow Tab.

You can read the detailed reference here. The following sections cover the main, key points when adding endpoints to your app.

Creating an endpoint

Creating API workflows (or "endpoints") is quite similar to creating normal workflows in your page, with a few differences.

Each endpoint should have a unique name; the Issue Checker will catch doubles. The name should be lower case, without spaces, as it will be used in the URL of the request to the API (see below)

Actions that can be used in an API workflow are server-side only actions, as defined in the Building Workflows chapter.

You can pick a few options regarding authentication and exposing the endpoint to the outside world.

  1. Expose as a public endpoint: check this box if you want to use the endpoint from another service (such as Stripe), or let other developers use the endpoint. If you're setting up a workflow for scheduled operations inside your app, this box shouldn't be checked.

  2. This endpoint can be run without authentication: an API workflow is usually run with an API key when triggered by an external service (see the Using the API section for more information regarding authentication). 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, sometime, 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.

Defining parameters

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 endpoint 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 endpoint as a response to a webhook.

One you have defined parameters in the endpoint 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.

Manual definition

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.

Automatic detection

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

Note that for the initialization to be effective, the request should be made to the endpoint URL, plus initialize at the end. The endpoint will look like

https://appname.bubbleapps.io/version-test/api/1.1/wf/endpoint/initialize

or

https://yourdomain.com/version-test/api/1.1/wf/endpoint/initialize

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.

Returning data from the API Workflow

Most API Workflows will run some actions, but under some circumstances, you may want to return some data. For instance, if an endpoint create 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. See this section of the reference for more details about this action.

Swagger Specification

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

https://appname.bubbleapps.io/api/1.1/meta/swagger.json
or
https://yourdomain.com/api/1.1/meta/swagger.json

You can read here more details about the Swagger Specification standard.

results matching ""

    No results matching ""