Comment on page
Creating API Workflows
This section covers how to create and setup an API Workflow.
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
Our webinar gives an introduction to how API workflows work
Creating an API Workflow works in the same way as creating regular workflows in on a page. After activating the Workflow API and accessing the backend editor you click Click here to add a backend workflow and choose New API workflow.
Click New API Workflow to create.
For each API workflow that you create and expose a unique endpoint is created, consisting of your app's Worfklow API root URL and the name that you give the workflow.
The root URL is made visible in the Bubble editor as soon as you activate the Workflow API as illustrated below:
Activating the Workflow API in Bubble's API Settings. exposes the root URL of your API workflows.
The complete API Workflow endpoint is constructed by combining the root URL with the name. As a consequence, the name of the API needs to be in a URL-friendly format:
- each API Workflow needs to have a unique name
- use lowercase letters
- remove spaces and special characters (replacing them with dashes or underscores)
- remove any trailing or leading white space
- don't make the name too long
For example, instead of naming a workflow Create New User, you would name it create-new-user.
Having activated the Workflow API and given our workflow a name, we can now construct the complete endpoint:
https://my-bubble-application.bubbleapps.io/version-test/api/1.1/wf/create-new-user
While the name of the workflow needs to be URL friendly, you are still free to provide a more humanly readable label for it. The API Workflow will automatically inherit its label from the name, but you can change this label as you see fit to make it easier to read and search for.
Giving your API Workflow a different label makes it easier to work with and search for.
Having created and named our Workflow, we need to make sure that it is exposed outside of your application, or the endpoint will simply return an error.
To be reachable from outside of your own app, this box needs to be checked.
Check the Expose as public API workflow box to give external applications access to the endpoint.
Only expose API Workflows that you intend to trigger from an external system. If you will only use the workflow as part of your own app's internal processes, keep the box unchecked.
Just like the Data API, API Workflows require that the client authenticates themselves before the workflow will trigger.
To set up an API Workflow to be accessible by anyone, check the This workflow can be run without authentication checkbox. Keep in mind that Privacy Rules can still limit the functionality of the API Workflow.
Be cautious when opening up API Workflows to be accessible without authentication as this will allow anyone to trigger the workflow at any time.
The HTTP method determines what kind of action the client instructs the server to perform. By default, API Workflows use the POST HTTP method, but some external systems require the ability to use the GET method for webhooks. To switch between the two, click the Trigger workflow with dropdown.
If you select to trigger the API Workflow with a GET request, the parameter definition will default to Manual Definition, and the field will be hidden. You can still define key-value pairs as normal.
If you are using API workflows via the App Connector, these workflows will automatically be triggered by the proper HTTP request defined in “Trigger workflow with” dropdown.
When you switch between GET and POST, the definitions and parameters you’ve defined will be preserved. The contents for Detect request data will be saved if you decide to switch between the different options of Parameter Definition. The Bubble issue checker will ensure the data is correctly formatted
In many cases an API Workflow will need some parameters to run. Let's say for example that you the workflow is set up to create a new User in your app, you will need to include key information like email and perhaps a first and last name. Using parameters you can send this information to the workflow from outside of Bubble.
You have two ways to define parameters:
- define the structure yourself
- 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.
Adding a parameter goes through three steps:
- 1.Give the parameter a name
- 2.Pick the type of data you will receive
- 3.Specify whether the parameter is optional or not
Both the type of data and optionality are important settings: Bubble will validate the data when a request is made and if a parameter is sent with the wrong formatting or a non-optional parameter is missing, Bubble will return an error.
In the example above we have include three parameters of type text to create a User:
- 1.Email (required)
- 2.First name (required)
- 3.Last name (required)
- 4.Nickname (optional)
Bubble can also automatically detect the parameters that are sent by an external service (webhook). It does this by "listening" for the incoming request and checking the parameters that are sent in the call – that way it can identify each one and attempt to determine what kind of data type it is.
To do this, you need to make a small amendment in the endpoint URL to let Bubble know that this is an initialization call.
Bubble can automatically detect the parameters in your call by using the Detect data feature.
To automatically detect data, do the following:
- 1.In the API Workflow inspector window, set Parameter definition to Detect request data
- 2.Click Detect data
- 3.Bubble will reveal the initialization URL
- 4.Send the request from the external system
Bubble will show you the URL you need to send the request to, but you can also construct this by yourself:
https://appname.bubbleapps.io/version-test/api/1.1/wf/endpoint/initializeor
https://yourdomain.com/version-test/api/1.1/wf/endpoint/initializeThe request should be made to the test version of your app, as it's the version you're modifying. You never need to send an initialization to the live version, as any changes you make to the parameters need to be deployed.
Overriding timezones in the backend requires that you activate the advanced setting Enable timezone override controls in your app's general settings.
API workflows allow you to override the time zone of the request by setting an alternative timezone with a static or dynamic choice. This helps you standardize the way in which your app parses and stores data. For example:
- if you parse 1/1/2000 from Eastern Time and keep the default setting, Bubble will save that date as 1/1/2000 12:00 AM Eastern Time
- If you instead override the client timezone with Pacific Time, selecting 1/1/2000 will save 1/1/2000 12:00 AM Pacific Time
This type of timezone standardization is useful in different scenarios:
- Where an external API request includes a timestamp, but not a timezone: you can set a static or dynamic timezone when that call is received to ensure its properly parsed
- Apps that deal with scheduling where the timezone of the scheduled appointment needs to remain constant: for example, if a user books a conference in London from Tokyo, your app can ensure that the timezone used is indeed London and not Tokyo.
Sometimes you'll want your app to return data after a workflow has been triggered. In most cases, to respond with data from your database you will want to use the Data API, but sometimes you need more control over what data you send back, such as:
- verifying that a workflow completed successfully
- returning data that depends on the workflow
- combining data/fields from multiple data types
To return data you can use the Return data from API action:
In the example above, we have a database Thing where we save a score. Let's imagine that we want to return the average score of all Things in the database. We can use the Return data from API feature to perform a search and return the updated average that depends on Step 1.
Last modified 8mo ago