“Robert Brooks is the Founder and CEO of MVP.dev, a development agency that specializes in building apps and MVPs with no-code tools and platforms, like Bubble.io. He has 24 years of development experience working with a wide range of companies; from startups to Fortune 500s.”
Setting up APIs in Bubble is one of the areas I get the most responses for when I ask platform users what their biggest challenges are when building their app. In this article, I’ll give a quick overview of APIs, Bubble, and then share the step-by-step process I use when setting up an API in Bubble. This is meant as a high-level, non-technical introduction, which should hopefully make it a bit easier to digest and won’t scare you!
First off, we’ll go through some definitions of key components of our integration. Then, we’ll kick off the guide, and I’ll walk you through the actual implementation of an API in Bubble.io. This tutorial will assume you had familiarity with Bubble.io already. If not, go through their lessons! I was a developer for 22 years, and I’m also the type that just likes to dive in and start playing with things and figure it out as I go along. That’s all well and fine usually, but with Bubble, when I jumped in, I quickly drowned and ended up floundering like a fish on a riverbank for hours. Don’t be a fish! Save yourself a ton of time and aggravation and do the tutorial lessons first! This is really one of the few times I think tutorials are absolutely necessary to get the full grasp and familiarity of what the Bubble platform can really do.
Next up is some boring definition stuff, but it’s here for completeness and for those who may not know what an API even is. You can jump down to the “The API Implementation Process in Bubble” section if you prefer to just get started.
What is an API?
The API usually provides a programming language-independent interface between various software components. In most cases, the components communicate with each other via the API by sending and receiving messages. They ease the programmer’s work by providing useful building blocks, which the programmer then uses to provide specific functionality.
What is API Documentation
An API can be a source of confusion if it is not properly documented. It is therefore important to document all the APIs and keep the documentation up to date. The purpose of API Documentation is to ensure an easy integration between two different systems. It is created to ensure that all the instructions are clear and concise so that anyone using the API can easily understand them.
One way that APIs are documented is with Swagger, now known as OpenAPI.
OpenAPI/Swagger
Formatting the API documentation in a more structured way allows us to automate the documentation process, making it easier for teams to generate and maintain them. While the OpenAPI Specification (formerly known as the Swagger Specification) and other API description formats have been around for a while, the latest 2.0 version has seen a dramatic rise in popularity. This is due in large part to how easy it is to use and the plethora of tools that are available to help devs generate, use, and maintain the documentation.
API Authentication Types
This can be one of the more difficult parts to wrap your head around when setting up an API. The primary purpose is to secure the data consumed or returned by an API and to ensure the person accessing the API is authorized to do so.
Some of the authorization types APIs use are:
Basic Authentication
This is a very common authentication method that’s used over HTTP. Using basic authentication, you send the username and password as the user, in the HTTP headers.
OAuth
OAuth is one of the more popular authentication protocols out there, and you may have heard of it. It’s used by all the major providers on the web. In OAuth, the client uses a secret to sign their requests, and the server validates that signature. This ensures that the client is who they say they are.
OAuth2
OAuth2 is the successor to OAuth, and it’s also fairly complex. It is used by several major API providers, including Slack, Google, and GitHub.
JSON Web Token (JWT)
A JSON Web Token is a string of characters that is used to represent information about identity. That identity could be a user, a device, or even another application.
There are two parts to a JWT:
The first part of the JWT is the header. This is where the type of the token is specified, as well as some metadata about the token (for example, the algorithm used to sign the token). The second part of the JWT is the payload. This is where the actual claims about the identity are stored.
A claims-based identity token is a string of characters that is used to represent information about an identity. That identity could be a user, a device, or even another application.
Alright, enough of all that mumbo jumbo. At least now when you review API docs, you’ll have a general idea of what you’re reading.
What is Bubble.io?
Bubble.io is an amazing no-code app-building platform designed to help you build software and applications without programming – using their visual interface to plan your application. Bubble.io will provide you with the tools you need to build a web or mobile application. To build a web application, Bubble.io provides the front-end interface, a workflow builder, and a database. You can then customize your application to fit your requirements with their drag-and-drop interface. It is very easy to use – you can create a new application in minutes. It also allows for API integrations, which overall makes the platform incredibly powerful.
What is Postman?
Postman is an app that allows you to create and test APIs, as well as share API calls with others.
The API Implementation Process in Bubble
Below is a list of the steps we’ll walkthrough for implementing an API in Bubble.
- API we’ll be working with
- Research your API
- Get the API information
- Setup API in Postman
- Setup API in Bubble
- Test the API
API We’ll be Working With
For this tutorial, we’ll be using the NY Times Books API to look at the Best Seller List from your birthday. Exciting! Well, if you’re not excited, you should be. Everyone should be required to know the NY Times Best Seller List from their birthday. I insist we mandate it.
Anyway, back to the task at hand.
Research Your API
The NY Times API documentation does a decent job showing you example calls on how to get a list of the Best Sellers. You can pick whichever list you like, but I’m going with hardcover-nonfiction because that’s what I read.
There’s also an example of how to pull a list by a specific date. Oh Joy! Our quest to obtain API enlightenment is one step closer.
Get the API Information
The instructions for getting your API Keys for the call are here. This is like many other platforms with API access and allows us to see how to use API keys in making a call. Be sure to enable the Books API when you create the app.
After you generate the app, your API Key will be available to use. You’ll need both the Key and the Secret to execute calls.
Setup and Test the API in Postman
If you don’t already have it, you can get Postman for free here. You’ll need to create an account with them to access the app.
After you log in, select the “New” button in the upper left-hand corner and then select “Request”.
When the Save Request form pops us, enter in “NY Best Seller List from My Birth” for the Request name, Create a folder to save it to called Bubble Tutorials, and hit Save.
What you’ll see now is the main Postman workspace. From here you can set up your API and test.
Let’s go through this one by one.
- This is the URL for the API call. For our example, we’ll enter https://api.nytimes.com/svc/books/v3/lists/names.json so we can get a list of all of the Best Seller lists available.
- Now click on the Params tab. Enter api-key for the Key and your Key from NY Times in the Value field.
- Now click the Headers tab and add a key called “Content-Type” and a value “application/json” since this is the content the NY Times API returns.
By the way, I figured out that the API key needed to be a query parameter by looking at the Examples Calls on the Books API page. Sometimes you need to do a bit of detective work to figure things out if the documentation is not all that great.
- That’s it for setup work! Now click “Send” and watch the API magic bestow you with a JSON document of NY Times Best Seller lists!
So from the results, decide which list you want to get the bestseller books from the “list_name_encoded” field. For example, I selected the “paperback-nonfiction” list. Why are we using the “list_name_encoded” field? Because URLs can’t have spaces in them, the “encoded” field gives us a list name we can use in our API call.
Remember when I said we were going to see the NY Time Best Seller list from your birthday? Well, I lied, unless you were born after June 8, 2008. Their API only has data as far back as that date. So we’ll need to pick a more recent date than that. For me, I picked my dog’s birthday. I’m sure my dog Rico will appreciate the list from his birthday as much as I would have. Or maybe he just wants a chew bone. He’s hard to read sometimes.
Now that we have our NY Best Sellers encoded list name, it’s time to get the books from a date we specified. If you look back at the NY Times Books API documentation page, you’ll see the format for making a date-specific call for a certain list:
In order to get our books, we need to update our API URL by replacing “/names.json” with “/{date]/{list name}”, where {date} is the date we want to pull the list for and {list name} is the list name we chose earlier. For this tutorial, I chose “paperback-nonfiction”. See below for an example.
Change it to:
Now click the Send button again and ta-da! Your NY Times Best Seller list is presented.
Interestingly enough, the #2 book on the bestseller list for Rico’s birthday was “Inside of a Dog” by Alexandra Horowitz. I’ll check with Rico, but I’m fairly certain he hasn’t read that one yet, so now I know what to get him for his birthday!
With all of this under our belt, it’s now time for us to move on to Bubble!
Setup the API in Bubble
Let’s go ahead and get a demo app in Bubble put together to implement and test our API call. Again, I’m assuming you’ve at least been through the Bubble tutorials already. If not, you may have a bad time. Seriously, go do them real quick and then come back!
Create a new Bubble app and name it whatever you want. When the New Application Assistant comes up, select “Start with a blank page” to make things easier, then close the assistant.
Setting Up the API Plugin
Click on Plugins in the left menu, then Add plugins.
Type “api connector” into the search box and then install the “API Connector” plugin. Click the Done button at the bottom after it installs.
You’ll now be at the API Connector’s plugin page. Time to get our API setup!
- Click the “Add another API” button.
- Enter “NY Times” for the API Name.
- Click the Authentication dropdown and select “Private key in URL
- Enter “api-key” in the Key name field and your NY Times API key in the Key value field
This gives you a basic setup for all NY Times APIs.
Now below the “Add a shared parameter” button, click the expand link.
Now we’ll set up the actual Best Seller book list API call. Do the following:
- Change the “API Call” field to “NY Best Seller List”.
- Change the “Use as” dropdown from Data to Action.
- Copy the URL in Postman up to the question mark(?) and paste that into the textbox next to “Get”. See the screenshot below for what mine looks like.
- Now, click the “Initialize call” button.
If your call was successful, you’ll see the popup screen below. Yes!!! You did it!! Now hurry up and click the “Save” button before something goes wrong! Just kidding. Click Save to accept the API response.
Congratulations! You now have an API officially set up in Bubble. Now, let’s do a test to see it in action!
Test in Bubble
To test, we’ll throw together a simple form with a button to kick off the API call and a textbox to show the results. We’ll also show how to create the workflow to make the call.
First off, let’s create a really simple data table. Click on the Data option in the left menu. Enter “Books” as the name in the “New type” field and click the “Create” button.
Now click the “Create a new field” button and add a field called Book with a Field type of Text.
Click on Design in the left menu to bring up the Index page.
Now drag a Text control onto the form. Click the “Click” link at the top, and select “Do a search for”. Select “Books” as the type, click the Close button, then add “Book” as the selected for value. See below for what my text control looks like.
Add a button to your page and change “…edit me…” to “Fetch Books”. Then click the “Start/Edit workflow” button to bring up the workflow screen.
Click the “Click here to add an action…” block and select “Plugins” and then “NY Times – NY Best Seller List”
Now click the next “Click here to add an action…” block, click “Data (Things)” and select “Create a new thing…” at the top.
Set the Type to “Books”, then click the “Set another field” button. In the red border “Click” element, click and select “Book”. Then select the next “click” element and select “Result of Step 1(NY Times – NY Bes…)”, then “’s books”, and finally “’s title”. When finished, it should look like the below.
Now we’re ready to test! Click the “Preview” link on the top right in the menu bar. Click the “Fetch Books” button, and a list of books should populate in the textbox element.
Outstanding. There’s a lot more that can be done from here, but this gives you a simple introduction to getting an API setup in Bubble.io
You’re Now a Bubble API Expert!
Or at least you’ve been exposed to the process now. As with anything, the more you implement APIs, the easier and easier it becomes. And just think, you now know the NY Times Best Sellers list from your birthday date of choice greater than 6/8/2008! Something I’m almost certain you did not know before our time together. You’re welcome!
Now get out there and build something! Check out our free courses that will help you get started.
Need help or support getting an API setup in your Bubble app? Ask the experts at BubbleHelpers.com!
