Forum Academy Marketplace Showcase Pricing Features

Updates to

As some of you may already know, I have been fortunate enough to have a chance to work with Bubble with the goal of improving the written documentation on

For the last few weeks we’ve been hard at work planning the coming updates and I’m excited to share the first batch of significant updates.

Let’s first dig into what we’re trying to do here.

First, it’s important to emphasize that the project focuses on the written parts of the Bubble manual for new. The goal with this project is to ensure that Bubble’s written documentation is:

  • pleasant to read, easy to understand and helpful for Bubble developers on both a beginner and advanced level
  • covering every aspect of their topic
  • generally of high quality

Project progress
The manual is a large body of work and updates will happen in steps. We have been collecting feedback from users of all levels to get an understanding of how the current manual is perceived and collecting suggestions for how it can be improved.

We have been using data on page visits to rank the importance of specific articles, combined with user feedback and our own general “common sense” for how updates can best serve the community. As a result, we decided to first rework the documentation covering the Bubble API and the API Connector.

Why these topics?
These topics were selected for the first batch of updates for a few reasons:

  • The existing articles had a high page visit count
  • The topic of APIs is among the more complex and challenging things to learn for new Bubble users
  • It would allow us to write about a technically intricate subject to learn more about how we can reach users of all experience levels – in other words: are we able to explain it in a way that makes both beginners and experienced users find it useful?
  • Lastly, it allowed us to test how it would be received if we spend significant chunks of the manual explaining technical details that are outside of the Bubble realm, such as how RESTful APIs work in general.

Article links
There are three series covering APIs, totalling 25 brand new articles:
Introduction to APIs
The Bubble API
The API Connector

Additionally, we have added an API glossary, as well as revamping the core reference page for Data API requests.

I’m excited to hear your feedback on the changes to these articles and whether you agree with the direction in which we’re moving.

Technical updates
We’ve also made use of some new tools to try to make the documentation easy to follow:

You will find annotations on technical terms in the new articles that you can click to get more information about a specific word, and sometimes links to extended explanations. We hope this will make it easier for beginners to understand the terminology without drowning the articles in too much repetitive explanations.

Expandable sections
If we find that a central part of the terminology of an article may need further explanation for some users, but we also think that a lengthy explanation would weigh down the article too much, we hide the extra information by default in an expandable section. We sometimes also use this to link to other sections that users may find relevant. In the example below, we give further insight into the HTTP protocol (which can be helpful to know if you are working with APIs), but many users would find it out of place in the article itself:

We have also tried to insert relevant links more broadly where we think it can be useful, as well as linking between the User manual and Core reference sections:

API requests documentation
To make the available Data API requests in our core reference more complete and easy to navigate, we have placed the calls in expandable sections that highlight the purpose, technical details and possible errors. Each call also includes a list of possible solutions to different errors.

Update log
One requested feature was for us to communicate more clearly when the manual has been updated. For example, agency owners may want to share that information with their developers to stay updated on important topics. You will find the changelog here.

Providing feedback
Each of the new articles now contain a link that lets you provide feedback for that specific article. You’ll find it in an expandable box at the top of each article:

Thank you for reading this lengthy thread, and I’m very excited to hear your thought on the updates and the direction we are taking. Over time, we want the Bubble Manual to become the best in the industry, and the way to get there is through the community.


Great job @petter and the gang! Overall I love the API section of the doc. I’m still reading through it. It feels the tech part of it is explained much better.

HOWEVER one thing I was gonna tweet at you and I think is crucial is TERMINOLOGY.

I’m still confused what’s the difference between: Backend Workflows, API Workflows, Data API & Regular API Call made from Front-end Workflow vs Back-end Workflow.

Confusion starts with definitions:

I can’t be the only one who thinks these 2 definitions are same, one includes the other…

Here’s another one:

Are not READ, CREATE, MODIFY or DELETE also Workflows? Can you perform any of these actions without Workflows?..

  1. If Data API means just the fact of enabling the app to perform API Workflows, why do we need a new term that confuses some users?
  2. What’s difference between Backend Workflow & API Workflow. Are not ALL Backend Workflows API Endpoints? Or maybe API Workflow are regular API call inside of a Backend Workflows? Or all Backend Workflows are just called API workflows?..
  3. What’s the difference between triggering a regular API Connector based API Call via Backend Workflow vs Front-end Workflow.

Anyhow, when I read the whole API section of the manual and talk to other Bubblers, I will find answers to these. But the point I’m trying to make here is we need simpler terminology & better descriptions. Otherwise I find it hard to communicate with other Bubblers. One person says something and another one says another thing, in reality they both mean the same thing…

P.S. If I’m the only one who’s confused please, ignore the message.

@bestbubbledev - Youtube | Patreon | LinkedIn | Twitter


I totally agree. As a beginner I feel same.

And still I haven’t got my problem solved in the forum about , how to handle a API response that has output file like image, audio, base64 files. No one would not want to waste time in finding these basic answers. Though I had to.

And I also think documentation and use cases of some major external API sources like Google, Microsoft, Amazon would help beginners and inspire a lot to build their first application in a fast manner.

I think a separate error handling part for the API and customizing the errors would help a lot to people.

A separate part of tips and tricks is important as well.

Basic FAQ’s are important to be answered in the manual. Like how many API calls can be made in a single workflow? Is there any limitation of showing alert messages or performance issues if I call multiple API’s at once?

Each type of API authentication needs to be more descriptive with examples if possible.

A separate part of performance issues related to API is important.

Note: All my points are related to external API’s.

I am still scared about backend workflow API so I try to avoid it.

1 Like

Great job. Big fan of everything you do @petter :slight_smile: - and can’t think of anyone better to do this tricky work. Very tricky work!

Agree with @bestbubbledev on terminology - it isn’t very clear. And will continue to confuse until a “root and branch” rethink on Bubble terminology is done. This may be beyond the scope of what you are doing as (for example) “backend workflow” is so ingrained in our language. But it may be worth at least trying to explain how we got to have multiple names for the same thing. Am totally guilty of throwing around all the terms without much thought, often in the same sentence.

The API glossary is an excellent idea, but having a quick skim it sounds like a coder wrote it. For it to be useful, it needs to be in a language most Bubblers will find helpful.

For example “RESTful” doesn’t mean that. RESTful doesn’t mean anything much at all. It means RESTish - SortaREST. But not REST. And Bubble’s data API is sorta REST but not actually. But nobody really needs to know all of that.

The point here is not to argue about the definition but whether it is even worth defining because it doesn’t matter if an API is “fully” REST or just a bit to the API connector. I just think it will confuse.

The only time it might matter is when talking to a coder about consuming your API to differentiate from SOAP/WebSocket/GraphQL. That is to sort of information that is useful to Bubblers.

Your books are so readable, it would be great if the Bubble manual were written in a similar style. Informative and chatty, and not afraid to invent concepts and words to aid comprehension.

Compare this to what is written (as a purely academic exercise) about APIs and resouces and states …

The person that wrote the “manual” on REST was an academic, and has probably never called an API in his life. Let’s not use his language.


Although “you” have now really broken the hover over reference in the Editor.


Is this intentional?

1 Like

Thanks for the great feedback guys! This is especially important on a topic like APIs since it’s both highly technical compared to other areas of Bubble and involves a mix of terminology from both inside and outside of the Bubble sphere. The curse of knowledge bias is very real and although I try to take it into consideration it wouldn’t be much of a bias if it didn’t steal manage to sneak one in on ya here and there :sweat_smile:

Based on your feedback it may make sense to set up a separate article for Bubble’s main API terminology to clear up some of the (understandable) confusion around it. Bubble internally are actually pretty consistent in how they use the terminology, but I agree it’s not as easy to grasp from the outside. I’ve tried to improve that in the updates, but it’s loud and clear that we’re not there yet.

Would it make sense to include an article that clears up terminology as part of the introduction to APIs series? The glossary can of course also clear up confusion, but I’m concerned that the extra steps of opening up the glossary page will stop most users from seeing it.

And I also think documentation and use cases of some major external API sources like Google, Microsoft, Amazon would help beginners and inspire a lot to build their first application in a fast manner.

We have one new article that focuses on a case with Google Cloud. I agree that making it easier to connect to major API providers is something that would help a lot of users, and this is something we’ve discussed and will prioritize – but it’s important to get the basic technical documentation down before we dive into specific cases. Or in other words: the tools to help you help yourself should be available before specific solutions. Secondly, we’re discussing the right media for it: text, video, etc.

Great job. Big fan of everything you do @petter :slight_smile: - and can’t think of anyone better to do this tricky work. Very tricky work!

Thanks @NigelG, I appreciate that, and likewise! :slight_smile:

The API glossary is an excellent idea, but having a quick skim it sounds like a coder wrote it. For it to be useful, it needs to be in a language most Bubblers will find helpful.

This one I take to heart for sure – it defeats the purpose of the glossary if it’s not easy to understand. My idea was for it to be a sort of “quick reference” (or indeed – a glossary) and not spend too much time going over each concept (as the articles take that long-form approach
already on many of the terms). But yes, if you look something up in the glossary and it makes you none the wiser, it doesn’t have much value.

There’s a lot of overlap between terminology explanations, glossary and FAQ and we’re probably not fully there yet. We need to be careful in this phase in particular to not spread key information out over too many articles.

Intentional… sort of :sweat_smile: as in – we knew it would happen, and wanted to get the new updates live quickly and knew there would be lag before tech could catch up. But they will be :slight_smile:

The feedback is greatly appreciated and useful, so keep it coming!

1 Like

Great to see OG @petter cooperating with Bubble to improve documentation :slight_smile:

From my point of view, it could be useful to add some “tips” sections to the manual and place examples and validated tips from the forum on some hot topics like DB structuring and connections, WFs and so on.

1 Like


It’s a point of frequent discussion how we can use the goldmine of great tips from the forum in the documentation to make it more accessible: but this too is currently a future priority until we get the basics right :slight_smile:

1 Like

Obviously such terminology should be included. This being said main articles should be consistent with the terminology. Otherwise the docs will be still confusing.

1 Like

Well, it is included, the question is whether it’s clear enough or if it’s too spread out and that a compressed article may make it easier to grasp and return when needed.

This being said main articles should be consistent with the terminology. Otherwise the docs will be still confusing.

Do you have examples where you find that the terminology is inconsistent? I agree the manual needs to carry the torch on consistency so I’d like to root out anywhere where it’s not.

I don’t see inconsistencies in terminology. But the Swagger Specification page broken.

Right you are! Will look into that.


You’ll find it here – the link from the editor (and several others) will remain broken until they’ve all been updated and deployed.

1 Like

I think what I was trying to say was that in many cases it actually doesn’t matter what the “real” definition is. As you say, you can look that up elsewhere and also be none the wiser.

Yeah, I think I got your meaning. The important thing is that it’s understandable and relatable for a person learning Bubble – not another technically precise piece of coder-jargon. It’s a good point, and I agree.

1 Like

I can’t know of any inconsistencies at the moment cause I’m all confused with these terminologies.
Workflow API / API Workflow… Initially I thought it was the same. Now appears it’s not. The rest of the confusion I’ve covered in the initial reply above.

Hey guys,

I’ve posted a new article now that covers the terminology in the Bubble API specifically – including the term Bubble API itself.

Bubble API terminology

Let me know what you think!


Hi @petter ,
Excellent job so far!
Say, … where can we give feedback to the team, regarding the work being done on the manual? here?
Anyway. a quick one here.

  • Check : Protecting data with Privacy Rules - Bubble Docs
  • Section : Examples/Example 1 Shopping cart => see the red numbers (1, 2, 3) on the 2nd snapshot of privacy rules. => I think the conditions “when …” are swapped for admin & own cart. (in the attached picture).

This is minor. But it can be misleading for beginners.

Hi @CharlesD ,

Ah, right you are, nice catch! I’ll see to it that we update the image. Thanks for flagging!

1 Like

This has been updated, thanks again for letting me know @CharlesD

1 Like