All posts

Organize your API documentation with Bump hubs

By Doug Sillars
Tutorial

Do you have more than one API that you share with your customers or your team? Or, multiple versions of one API? If you do have many different API specifications, it can be difficult to organize and share your documentations in a coherent way. This is why Bump developed hubs.

What is a hub?

A hub is a group of API documents. This way you can organize and share your various specifications (be it multiple endpoints, versions, or just a way to organize many microservice APIs). The hub page is a root listing of all of your APIs, and you can organize your documentations inside the hub in any way you wish.

Let’s see how it works in action.

Creating a hub

To begin organizing your API docs, you’ll need to create a hub. In your Bump Dashboard, click “+New” at the top, and choose “New hub”

New hub menu screen

This will open a page to create your new hub, where you supply a name, and if you already have standalone APIs in Bump, you can choose to add them to the hub:

I would like to organize my various JokeAPI documents using a hub. At the time of this blog post, I have 3 versions of my API:

  1. Joke Blueprint: OpenAPI specification that I am using to define my API.
  2. Joke 001: The initial commit - with just the admin upload endpoint added.
  3. JokeAPI - updating from GitHub Action: When changes are made in GitHub, this documentation is updated automatically. This is the “current” API document.

Bump create a new hub screen

I named my hub "Joke API Creation". Once created, I was taken to my dashboard. I added each document from my dashboard, using the “New documentation” button and adding each API document sequentially. Here is a screen shot after all 3 documents were added:

Bump Joke API hub dashboard screen

Looking at my APIs

Bump Joke API hub documentations screen

When you first create your hub, all the documentation is grouped together (in the “all documentations” category). Perhaps that is all you need - now your users can easily navigate between the different documentations, and they are all in one convenient place.

hub Categories

In my case, one Document is my blueprint, and another is my initial commit - neither are really meant to be used. I’d like to mark those in such a way to denote that they are not the active API, but are present for historical reasons.

I can use the hub category feature to do this. You can see this in action with the Bump demo hub where there are 4 categories:

  • Last deployments
  • Public
  • Services
  • Tools & external APIs

To group by categories, enter your hub settings, and change the Customize UI:

Bump hub Customize UI screen

Click the “Update UI settings” button to save this parameter.

Next, you must tag each API with a category. In your hub settings, go to “Documentations” where you will find each API in your hub.

Bump Joke API hub dashboard documentations

In the Settings for each Documentation, you’ll see a “Hubs settings” section. Here you can assign the documentation to a hub, and add a category. For my Joke 0001 documentation, I would like to categorize as "initial":

Bump documentation hub settings

Complete this for each API, and now your hub will appear with each API listed by category:

Bump Joke API hub by category screen

The categories are listed in alphabetical order, so it is convenient that the “active” API appears first.

Now, anyone visiting my hub can see the evolution of the JokeAPI documentation, from Blueprint to the initial API commit, to the active API documentation. The number of documentations will increase as the API continues to be built, but they will always have a nice organization to them thanks to the hub interface.