What is a RESTful API?
This section covers what it means that an API is RESTful and how a RESTful API call is structured
Last updated
Was this helpful?
This section covers what it means that an API is RESTful and how a RESTful API call is structured
Last updated
Was this helpful?
RESTful APIs use the HTTP protocol to initiate a connection with a server and get a response.
REST, or Representational State Transfer, is not actually a protocol, but more of a set of guidelines that define how a client and server should interact with each other. In other words, a developer can technically build an API to follow any kind of structure they want, but REST is a widely adopted style of architecting APIs that’s flexible, scalable and easy to understand.
This makes it easy for different systems to talk to each other as their developers prepare it to follow the same method of communicating. The RESTful style follows a few key principles:
The client-servers are completely independent of each other and only communicate using the REST API.
It’s stateless: this means that the server does not store any information about the client between requests. As such, each request is completely isolated and contains all the information needed for the request to be processed.
It’s often cacheable, meaning that the client uses a cached response if the user requests the same data multiple times. This speeds up the client application and lightens the load on the server. Bubble automatically caches data instead of repeating a request, unless it needs to.
RESTful API’s are often described as layered since the client doesn’t necessarily have direct access to the server, but can be separated by intermediaries such as a proxy to ensure the stability and security of the server
This may all sound very technical, but don’t worry: most of this is automatically taken care of and simply works.
Bubble automatically generates an interface in your app that adheres to the RESTful principles, making sure that both incoming and outgoing connections are compatible with thousands of external systems.
As we’ve seen, an API request based on REST principles allows two software systems to communicate with each other in a way that both systems understand. Each request/response is made in complete isolation from each other, and the server receives all the information it needs to process the request in that request.
But what does the call actually look like? What kind of information is being transmitted?
A good thing about the RESTful architecture is that the data being transmitted in both directions is designed to be readable both by computers and humans. Each call consists of recognizable parts that each serve a specific purpose. The call is made using the HTTP protocol.
You have probably heard the abbreviation URL, but you may not have thought much about what it means. In the context of APIs the abbreviation makes sense: Universal Resource Locator. In the earlier section, we talked about how a resource is a specific piece of data or functionality that can be accessed through the API. It follows that the URL is the way to find that resource. In other words, the URL points the client’s request towards the right resource on the server.
In Bubble’s Data API, endpoint URLs are automatically generated for each Data Type and API workflow you choose to expose.
https://myapp.bubbleapps.io/version-test/api/1.1/obj/datatypename
https://myapp.bubbleapps.io/version-test/api/1.1/wf/workflowname
This is the first part of a RESTful API request. This too makes sense: in order for the server to authenticate a client and check the client’s authorization to reach a specific resource, we need to know which resource they are trying to access.
Now that we know which resource the client wants to access, we need to know what kind of action they want to perform. Remember that we discussed HTTP being a protocol: that means we have a set list of possible actions that we can ask of a server that is prepared to receive HTTP requests. The list of possible HTTP methods is longer than this, but the most common actions you’ll see are:
GET
Retrieve data
POST
Create data
PUT
Replace data (empty values s)
PATCH
Partially update data (empty values )
DELETE
Delete data
As you may have guessed by now, the same thing happens with the other actions: your browser sends POST, PUT and DELETE actions to the Bubble server to tell it to create, modify and delete things in your database.
Now it’s starting to make sense why HTTP requests make up the foundation of the web: since every web browser and server speaks the language of HTTP actions to view, create, edit and delete data.
Every API request and response contains a header. This is where you’ll find what’s called metadata or information about the data being exchanged between the API and its clients. A lot of different data points can be included in the header, but the most common ones you’ll come across working with Bubble are content–type and .
The Content-type is used to specify the media type of the data being transmitted so that it can be properly interpreted and processed.
For example, if a client is sending data to a server in the form of a , it might include a Content-Type header with a value of ‘application/json’ to indicate that the data is in JSON format.
In our earlier example of fetching the bubble.io web page, the Content-type would have a value of ‘text/html’ to indicate that the client is expecting an HTML document in response to the request.
The authorization contains the information needed to authenticate the client sending the request. In the case of Bubble’s API, Bubble accepts what’s called a Bearer token. In an HTTP header, that line would look like this:
Authorization: Bearer <access-token>
Bearer simply means that the client is a bearer of the given token. The token is a kind of password that the client has to authenticate themselves, often referred to as an API key. An API call doesn’t have to include authorization: it’s only needed when the API is not public.
The body can contain additional data, such as the data being sent in a POST, PATCH or PUT request (GET requests also sometimes contain parameters in the body). After all, if you want to create or modify something in the database, you need to include the information that you want to store, such as a user’s email and name. The body is better suited than the URL to hold complex or larger volumes of data.
Here's an example of what the body of a POST call might look like. In this example we're creating a rentalunit with three parameters: a name, a number and an isRented :
The information you see in this example is formatted in the JSON format.
Let’s imagine we’re building a system for keeping track of rental units, and we need to send an API call to the app to create a new rental unit. Putting together all the parts we’ve gone over the request may look something like this:
In this example, the URL contains the resource we want to access (rentalunit), the HTTP method is POST, the headers include Content-Type and Authorization, and the body contains the data being sent to create a new rentalunit.
In the next sections we'll cover how you can set up incoming and outgoing requests with Bubble's different API tools.
When your browser contacts a server such as in order to load the webpage, it’s sending a GET request to the root URL of the domain. The bubble.io server has been set up to respond to such a request by responding with the necessary data to render the page in the browser, such as a HTML and CSS file.
In GET requests, the URL can sometimes contain parameters, such as the constraints for a search whereas in POST/PUT/PATCH/DELETE requests parameters are usually contained within the .
