So I have a client who wants their POS form integrated with my bubble app (basically, they want a waiver form to shoot a webhook with customer info to my bubble app each time it is submitted). The POS company has asked me for my API Docs so they can get an idea of what type of development they’re looking at.
I don’t yet have docs, and as a non-coder who is somewhat familiar with APIs (but not very), I’m unsure of what to tell them.
I was thinking something like: “Although we don’t yet have API documentation posted, we would simply need you to shoot a webhook to us each time one of their waivers is filled out. We require a JSON payload.”
Does that sound somewhat accurate for what you would tell them? Is there a structure I should be requiring from them?
I’m another non-coder, and I imagine they’re also going to want to know what tables and fields they can post to. With APIs, like most coding, the devil is in the details. And, the better the documentation, the more of the details are explained up front so people can understand what’s actually required without having to go through trial and error.
Seems the like article @StevenM sent provides a great way to get something useful done quickly. The specific code examples are likely really helpful for developers POSTing to your API.
tldr:
Actually you can easily automatically generate an API documentation for any bubble app.
This is because bubble creates a swagger specification for every app.
And you can automatically generate api documentation from the swagger specification using a tool like swagger.io
Read more below–
For documenting your bubble’s API I find swagger.io the most simplest expecially for a non-coder.
What makes this very simple is that bubble generates a swagger specification for every bubble app.
So you can simply just import this file and boom you have an API documentation generated for you that you can share with anyone.
Here are the details:
So for every bubble app you can access the swagger specification from:
Live https://app-name.bubbleapps.io/api/1.1/meta/swagger.json
Development https://app-name.bubbleapps.io/version-test/api/1.1/meta/swagger.json
where app-name is your bubble app name. If you have setup a custom domain replace the app-name.bubbleapps.io with your custom domain.
Before I go into creating a formal documentation lets look at how we can quickly see how the documentation will look like.
Replace the swagger link in the input box at the top of the page with your app swagger link as explained above.
Hit Explore. Boom you have a full documentation of your bubble application workflow and data api.
The amazing thing about this is that you can even test your api live from this documentation.
When you click on any api endpoint, you can supply the parameters and test it live here.
Now that we have seen how our api documentation will look like we can create an account on swagger.io and create an formal api documentation we can host online to share (either privately or publicly).
Click on Import and Document API. If this is your first time will likely popup. If it doesn’t just popup click on New on the left side and select Import and Document API
Enter your bubble swagger specification link as above.
You can set the Visiblity to public or private. Private means you will have to add a collaborator before they can see the documentation. Public means you can share a public link of your documentation with anyone.
Click Import and you’re done. You will have a full documentation of your bubble application api.
There will be share link that you can share with anyone.
There are other useful stuff and advance stuff you can do but this is just enough for your use case.
Edit:
For those not familiar with Dropsource, it is this same swagger specification that you use to import your bubble api endpoints into Dropsource so that you can get from and add data to your bubble app from within Dropsource.
Not a huge deal, but my team is wondering if it’s possible to have an API endpoint that doesn’t contain “bubbleapps.io” if I’m trying to keep my app white-labeled?
@StevenM yes its really very helpful tool.
Its my go to tool for testing my bubble api endpoints.
You can also even go https://editor.swagger.io/ and paste your swagger specification there and you will be able to make some edits to your swagger specification.
If you’re building an app with bubble+dropsource this is a must have tool.
