As you start getting into Bubble.io, you inevitably come across the term API. It’s one of the most powerful no-code features there is, and can open up endlessly exciting opportunities for your application with just a few pretty simple steps. But what is an API?
In this introductory guide, we’ll go over what an API is, how it can greatly extend the features of your Bubble application, and how you can learn to set it up yourself.
What is an API?
Whenever two machines need to exchange information, they don’t need a fancy visual interface like you and me do. The nice design, buttons, icons and images that we like so much would be a hindrance for a machine trying to interpret the data. No, a machine prefers it straight up – as raw, predictably formatted data with no bells and whistles. On today’s internet, many of the apps that you use daily increasingly rely on REST APIs to deliver their services. It’s so common in fact, that it has become a big part of the foundation of the internet works. Apps constantly communicate with each other to make things easier for you, serving up everything from your own calendar appointments and files to news articles, weather predictions and secure payment methods.
API is short for Application Programming Interface. You are using it every single day without thinking about it: in fact, when you opened up this website, your browser sent an API request to the server using the http protocol, and the server returned website data in the expected format to your browser. Voilà – you’re reading this article in the HTML format that I intended.
The same thing happens every time your Bubble application performs a database query using Do a Search for: Bubble uses the external Elasticsearch API to search and aggregate data. You can identify and check what that call and response looks like in our guide on using Google Developer Tools with Bubble.io.
Ok, so these are good examples of the numerous ways APIs are working behind the scenes, but they don’t feel very relevant to your everyday work as a Bubble developer. It’s probably not what you think of when you hear API either. So let’s ask a few more relevant questions that hit closer to home:
- How does your phone know the weather tomorrow?
- How can Calendly add appointments to your Google Calendar?
- How does Zapier connect applications by the thousands?
The answer is of course that these applications communicate through an API connection, allowing access to cross-platform collaboration and sharing of information. Across the web you can find thousands of service providers that offer information or functionality that other developers might need. Some of them are free, some are paid and others can be public information offered by governments (such as public statistics). REST APIs are the glue that holds the SaaS economy together.
Let’s look at a few well-known API examples:
- Google Maps lets you display maps, find directions and coordinates and view satellite imaging
- Giphy let’s you search through millions of GIF animation files.
- YouTube lets you integrate video, upload videos, download statistics, stream live and other features.
- Google Calendar lets other applications see your availability and create/edit appointments
- Stripe and Paypal let you accept payments and offer subscriptions without worrying about security
- Facebook lets users log in to other sites and platforms using their Facebook credentials
- WeatherAPI offers real-time, future and historical weather data
- Azure Image Analysis can analyze and understand the content of photos (such as flagging adult content and recognize human faces)
As you can see, APIs are not simply a way to get data from another database. They can also be called upon to perform calculations and operations on data that you provide, such as analyzing the content of an image, encoding a video file or translate a string of text into another language.
How do APIs work in Bubble?
Ok, so an API is a way for applications to talk to each other, but within strictly defined rules. APIs don’t give access to how an external application actually works – but it gives a line of communication where you can ask the application for specific information or to execute a command within its own internal system. Our example with Bubble’s own Do a Search for illustrates this point: you can ask Bubble for information and get a response. But you don’t know, and can’t affect how the search is actually performed. That process happens behind closed walls.
Asking a weather API is the same: your browser sends the server a query that specifies a place and a time and you’ll get the weather report in a neat, readable format in return, but you have no control over the weather stations, algorithms and staff members who helped make the information available in the first place.
The API is often called a layer, since you’re not actually peeking into the actual inner workings of the application, but only standing on the outside talking to a very strict guard who only allows you to ask a predefined list of questions. The communication happens between a client (the computer that makes the API call) and a server (the computer that offers the API as a resource).
For any application, Bubble or not, API communication can be split into two basic categories:
Incoming API requests are instances where your app does not initiate the call, but accepts a request from somewhere else. In this case your app is the Server.
Outgoing API requests are instances where your app initiates an API call to a server. In this case your app is the Client.
How are API calls made in Bubble?
Bubble uses the most common API method on the internet, known as REST (Representational State Transfer). This is not a protocol on its own, but it uses the HTTP protocol to access a URL with the needed parameters, and the server sends a response back, typically in JSON format. JSON is a data format that’s easily readable for both humans and machines, making it perfect for data transfer between different systems: because the data is predictably formatted, the client computer will recognize it, and because it’s also easily readable to humans, it’s easy to understand and debug as you set the connection up.
Authentication and authorization
In most API calls the Client needs to somehow identify itself in order to get access to resources on the Server. This process consists of two similar words with different meaning: authentication and authorization. To be able to talk about APIs, we need to know the difference between the two.
Authentication is the process of verifying who someone is. In real-life, you might compare that to showing your passport at the airport. Just showing up is not enough, you require some sort of identification to confirm that you are who you say you are. In an API call, authentication can be done in many different ways, and Bubble uses a unique string known as a token to identify any Client that sends a request.
Authorization is the process of determining what kind of resources a Client has access to after it has identified itself. Going back to our travel example, showing your passport and confirming your identity helps the airport determine what you are authorized to do, such as boarding the plane and visiting a VIP lounge.
The request
A call consists of a request sent by the Client and a response sent by the Server. Let’s have a glance at what that looks like behind the scenes. Using Postman (an app for testing API calls) I’ve set up a request to a Bubble app to search for and send me back a list of Contacts. The call looks like this:
GET https://myappname.bubbleapps.io/version-test/api/1.1/obj/contact: {
"Network": {
"addresses": {
"local": {
"address": “000.00.0.0”,
"family": "IPv4",
"port": 00000
},
"remote": {
"address": “000.00.00.00”,
"family": "IPv4",
"port": 000
}
},
"tls": {
"reused": true,
"authorized": true,
"authorizationError": null,
"cipher": {
"name": "TLS_AES_256_GCM_SHA384",
"standardName": "TLS_AES_256_GCM_SHA384",
"version": "TLSv1.3"
},
"protocol": "TLSv1.3",
"ephemeralKeyInfo": {
"type": "ECDH",
"name": "X25519",
"size": 253
},
"peerCertificate": {}
}
},
"Request Headers": {
"authorization": "Bearer MY-API-TOKEN”,
"user-agent": "PostmanRuntime/7.29.0",
"accept": "*/*",
"cache-control": "no-cache",
"postman-token": “postman-token,
"host": “myappname.bubbleapps.io",
"accept-encoding": "gzip, deflate, br",
"connection": "keep-alive"
},
The beauty of no-code and Bubble is of course that you mostly don’t need to know about these things. These connections are mostly generated for you. Note the code in bold here: the first one tells us that we’re using a GET request (meaning that we are requesting information, not changing anything), and we’re pointing it to the endpoint that specifies the Data Type we want. The second point in bold is the authorization needed to access this information. The part that says MY-API-TOKEN would be replaced with an actual API token generated by Bubble in the settings below:
The response
The information that Bubble sends back to the client looks like this:
{
"response": {
"cursor": 0,
"results": [
{
"Name": "Contact 1",
"Created Date": "2022-01-14T16:40:29.139Z",
"Created By": "admin_user_appname_test",
"Modified Date": "2022-01-14T16:41:15.673Z",
"_id": "1642178429159x231315341776228334"
},
{
"Name": "Contact 2",
"Created Date": "2022-01-14T16:41:06.444Z",
"Created By": "admin_user_appname_test",
"Modified Date": "2022-01-14T16:41:06.455Z",
"_id": "1642178466644x819763845791344115"
}
],
"remaining": 0,
"count": 2
}
}The response actually contains a bit more data than this, but for simplicity’s sake I’ve included only the actual database data.
The purpose of your app is of course to make data more visually appealing, so you take this data into your app, and you format it in a way that makes sense to your Users: you replace the raw weather data with nice sunny/cloudy icons and instead of displaying the URL of an image, you show the actual image. Perhaps you aggregate the data, showing the average game points of your favorite sports player or the median income of a particular category of employees.
What are Bubble API endpoints?
In the example above, we talked about an endpoint. API endpoints are any point of entry into your application from an outside system. APIs and endpoints are not the same thing – rather an endpoint is a part of an API system. For most web applications (Bubble apps included) each endpoint is represented by a unique URL by which the API can access a specific resource.
In Bubble, this means that every public API Workflow and each public Data Type gets a unique URL that a client can access. All endpoints in your app start with a base path (Bubble calls this API root URL), which identifies your app’s URL, and then a subfolder and endpoint that points to the right endpoint. You’ll find the base path under Settings – API when you activate the different sections of your app’s API as illustrated above.
A Data API endpoint would simply take the name of the data type like this:
https://myappname.bubbleapps.io/version-test/api/1.1/obj/contact
And a Workflow API would use the name of your workflow in Bubble’s backend editor:
https://myappname.bubbleapps.io/version-test/api/1.1/wf/name-of-workflow
How Bubble works with APIs
Bubble let’s you facilitate for outgoing and incoming API connections in a few different ways:
The Data API (incoming)
The Data API lets external services connect to your application’s database and Create, Read, Update and Delete (CRUD) records. Each public Data Type in your database generates and endpoint in a subfolder called obj:
https://appname.bubbleapps.io/version-test/api/1.1/obj/data-type-name
When you activate the Data API, you can select which Data Types in your database to expose. If you authenticate your Users via a Sign Up/Sign In action in an API workflow or you’ve set up your app as an SSO provider, the exposed Data Types are protected by Privacy Rules, just like your regular database. If you provide the API client with an API Token from the Bubble editor, they will have full access to all data.
API Workflows (incoming)
API Workflows let you create custom workflows that can be triggered by an external service through an API call. Each API workflow you publish generates an endpoint in a subfolder called wf:
https://appname.bubbleapps.io/version-test/api/1.1/wf/workflow-name
The API Connector (outgoing)
The API Connector plugin lets you authenticate and connect to an external service to use as a Data Source or Action. In this case you are using someone else’s API, so this doesn’t add any endpoints to your app. Instead, you are accessing one of their endpoints.
Find the right Bubble.io API connection type
As you can see, what type of Bubble API connection you need to set up depends on exactly what you want to do. If you want to share your app’s database with another system, you can set that up using the Data API. If you want other systems to be able to kick off specific workflows in your app or use webhooks, then you set those up as an API workflow. To connect to external systems (such as Stripe, WeatherAPI and Google Calendar), you’ll need to look into setting up the API Connector.
