Jun 25, 2021

📲 Building an API & documentation for your NoCode app - Issue #5

James from NoCodeSaaS

Happy Friday!

One common thread among the most successful SaaS applications is that they offer a comprehensive API to their customers.

APIs enable you to interact with a service to manipulate your data, trigger off actions and export data to other services.

Hopefully, you’ve started getting to grips with the API Connector in Bubble and have experienced some of the power using APIs can give you.

In this edition, I’m going to cover how I gave my Bubble app UserLoop a comprehensive API.

We’ll be covering…

How to structure and create the API in Bubble
How to handle authentication with API tokens
How to test your API using Postman
How to create your API documentation automatically
How to allow customers to add their own Webhooks to be notified of changes within your application.
Speeding up your API using Amazon API Gateway

So, let’s get started and dive in!

How to structure and create the API in Bubble

There are a couple of ways you can approach this.

Bubble does offer a built-in Data API that allows you to manipulate the data in your app, but the handling of authentication in this didn’t quite match what I wanted.

To build my API, I instead decided to use Bubble’s Backend Workflow feature. This lets you handle authentication yourself, and gives you more control over how you structure your API.

Creating API Tokens

The first thing we need to do is consider how we are going to secure our app’s data and ensure only authorised users are able to access data through the API.

To do this, I recommend creating a new data type in your app’s database called ‘API Key’.

Depending on your app’s structure, this data type should be joined with your ‘company’ or ‘user’ entity so that every customer of your app is able to create multiple API keys.

You join it as the type ‘contains list’ to your company/user so that each user or company could have multiple API keys if needed.

I recommend giving your API Key data type two fields…

Active. This tells me whether this key is currently active or disabled.
Company. This tells me which Company this API key is linked to.

This is how my APIKey field is structured.

Now I have this new data type set up, I can build a simple UI in my app which lets users view, create, delete and disable their API keys.

You might be wondering what the actual API key is in this example.

For the actual key, we are going to use each entries Unique ID as the actual key itself.

How to handle authentication with API tokens

Now that our users have the ability to create and manage their API tokens, we need to start work on building our workflows to enable them to interact with them.

To do this, you will need to make sure you have Backend Workflows enabled in your app’s Settings > API menu.

Right, let’s get started creating the Workflows for our API!

First, we’ll head to the backend workflow section.

I recommend creating a folder called ‘Public API’ to store all the workflows for your API - it keeps things tidy and easy to manage.

The backend workflows that power the UserLoop API

For the first endpoint, I’m going to make a simple API call which will return whether or not an API key is validate, let’s call this endpoint Key Validator.

Now, we only want this workflow to run when someone has a valid API key, so we need to make an ‘Only when’ rule to check that before this workflow should run.

Our workflow should have a field/key called ‘key’ which is what will accept the request’s API key.

Expose the workflow as a public API workflow and add the 'only when' rule.

As you can see, I have set the workflow only to run in these certain conditions….

The API key is valid (we’ve searched for API Keys and found a match for the key provided)
The API key is active. Here we’re checking that the key itself is active. If the key was marked as active=no the workflow would not continue to run.

The next thing we need to do is return some data from the API in the workflow if the key is indeed valid.

Use the Return Data from API action to return data.

As you can see, we’re returning the message ‘This is a valid API key!’ if the user provides a valid key in their request.

You can use this same technique to create each endpoint your API might need.

How to test your API using Postman

As you build out your API you will need to test it as you go to ensure it’s functioning correctly and providing back data as expected.

I recommend downloading the Postman app to do this, you can add each API call here and store it as a collection.

The Postman console where you will test your API

There are several other benefits to building and testing your API with Postman.

The first is that it can automatically create professional and easy to use documentation for you.

This lets your customers know how they should interact with the API, and even gives them a template to get started.

For example, here is the documentation for the UserLoop API, you can use this as a guide for starting to test your own.

How to allow customers to add their own Webhooks to be notified of changes within your application.

Depending on your app, you might want to give users the option of creating a webhook to be notified of changes in your app.

This means, whenever a specific action happens in your app, it can make a call to the webhook URL they provide containing data about the event.

The way I have achieved this in my own application is with an interesting user of Bubble’s API connector.

I have added a new API for ‘Customer API’ which I call from any backend workflow when the user completes an action.

The Customer API in API Connector used to send webhooks to customer endpoints.

When the user completes an action, the workflow then calls this ‘Customer API’ to trigger sending a webhook to their desired endpoint. This could be Zapier or anything else.

As you can see from the setup above, the actual webhook URL is dynamicly set as [endpoint]. This means the customer’s webhook endpoint which is stored in the database is used to send out the Webhook, meaning whicveer service they have chosen is notified.

Speeding up your API with Amazon API Gateway

For certain advanced use cases you may find that Bubble is too slow to respond to API requests - it usually takes a few seconds.

If you need a super fast response for your API calls - perhaps if you are embedding content on a third party site and it needs to load immediately, Bubble might be too slow on it’s own.

There is a solution which can drastically speed up responses from your Bubble API.

Amazon’s API Gateway is a layer which you can install between your Bubble API and the end user.

The API gateway can be given a pretty URL for customers to access, something like api.yourapp.com instead of the out of the box Bubble structure.

The gateway can also cache responses, meaning they are delivered lightning fast.

This is quite an advanced use case so I’m not going to cover it in depth today, but if it is of interest please do drop me a reply and I’ll be happy to share more!

Don’t forget your privacy rules.

As always with Building in Bubble, don’t forget to correctly configure your privacy rules to protect your user’s data.

Petter @ Amlie Solutions has just published a fantastic guide on Privacy Rules which I highly recommend checking out.

Getting your privacy rules right and understanding how they work can save you huge headaches down the line!

Thanks for reading

I hope you enjoyed this issue - there’s lots more to come!

I’m considering starting to record occasional video tutorials to cover some of the more advanced topics in my newsletter, would that be useful to you?

Let me know with a reply!

Thanks again, James.

Did you enjoy this issue? Yes No

James from NoCodeSaaS @jamesdevonport

If you're thinking about building a SaaS product using no-code or visual development tools - this newsletter is for you!

Every Friday I'll be sharing practical tips and advice on building a SaaS app using the Bubble.io platform.

From how to structure your database, to implementing 3rd party APIs, we'll touch on everything you need to know to get started and scale your app to thousands of users.

I'll be using my own Bubble app as an example. I'm currently building UserLoop.io - a Shopify App designed to help store owners automatically survey their customers and get more reviews.

In order to unsubscribe, click here.

If you were forwarded this newsletter and you like it, you can subscribe here.

Created with Revue by Twitter.