API Documentation with API Blueprint

Last Update: 15.11.2017. By Jens in APIs | API Business

This is the second part of the API documentation series. In the first, we covered for whom the documentation is written, what it should contain and the three different types of writing it. Starting with this part, we dive a bit deeper into the latter and explore some standard formats and ways of writing.

When writing an API documentation, one quickly realizes that it is beneficial to follow a particular structure and that you are repeating this for every endpoint. Endpoint B should be described in the same structure as endpoint A.

Of course, you can define your own structure, but when you start out with such an endeavor, change is inevitable. And you have to adjust the docs every time if you want to keep it understandable and consistent.

This frustration led to a few almost standard ways of describing an API, especially in the area of REST APIs. Some of them are tech stack agnostic, and some are for a particular tech stack.

We will cover the tech agnostics first.

• API Blueprint

  API Blueprint is simple and accessible to everybody involved in the API lifecycle. Its syntax is concise yet expressive. With API Blueprint you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs.

• RAML

  RESTful API Modeling Language (RAML) makes it easy to manage the whole API lifecycle from design to sharing. It’s concise - you only write what you need to define - and reusable. It is machine readable API design that is actually human friendly.

• OpenAPI

  The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service

We will cover API Blueprint in this part and the other two plus a platform specific one as an alternative, in this case, Spring REST Docs, in the following articles.

API Blueprint

API Blueprint is a specification format for describing web APIs. The idea behind is to describe the API before you build it in a human readable way and with as less fuss as possible. It is a type 1 of our classifications made in the overview - you write the docs separate.

The format is based on the Markdown syntax and extends it with the structure needed to describe APIs. Markdown is commonly used and loved because it looks like regular text and you can understand it without knowing the syntax at all. It is almost the same with API Blueprint if you know some basic vocabulary of the web.

Once we have written our documentation, we can use one of the plenty tools available, to transform it into a useful looking documentation and also use it as a base for generating code or before that providing a mock so you can test and interact with it during the design phase. We can even run checks to verify our implementation matches the documentation.

Here is a sample describing a simple book metadata API.

FORMAT: 1A

# Book Metadata API
A simple example for retrieving book metadata.

And a bit more to tell..

## Book  [/books/{isbn}]
Metadata of a book.

+ Parameters
    + isbn (number)

        The ISBN of the desired book.

+ Attributes (Book Base)
    + id: 9781 (number, required)

### Retrieve a Book [GET]
Retrieves the Book with the given ISBN.

+ Response 200 (application/json)
    + Body (Book)

We basically define a /books/{isbn} endpoint which expects an ISBN in the path and will return a book object with HTTP status code 200 (success) when called with an HTTP GET request.

One can read it without knowing the syntax. When we use docprint, which transforms an API Blueprint doc into an HTML page, it might look like;

On the left side, it will display a TOC. In the middle are the sections with each request and the objects involved. And on the right, it will show a pane with example request for a set of languages. All based on our single API Blueprint file; out of the box.

Advantages

It is plain text and not tied to any software. Your developers can write in their favorite Markdown editors. Yet it is simple enough that your product owner or other non-developer staff can use it.

It also defines a structure which guides you building a useful documentation. You don’t have to come up with one yourself.

It has a small but healthy ecosystem of tools around it and probably won’t die in the next month. There are libs to parse and render it so you could extend it with your own tooling if necessary.

Disadvantages

While writing and generating the final documentation is tech agnostic some benefits of the spec and tool environment around it, might not be available for your particular tech stack. This is not a disadvantage when you use it as is but might be one if you want to add your own tooling.

Markdown and thus API Blueprint work a lot with indents and whitespace which is unfamiliar for some and sometimes can be painful to find problems in the formatting.

It is built around APIs using regular HTTP. If you happen to build a different API like file exchanges, Queues, etc. it does not fit.

Conclusion

Using Markdown as a base was a smart decision. Most people can pick up standard Markdown syntax in a short time and become productive with it. API Blueprint is a mature spec, and the documentation and examples are plentiful. The ecosystem around it is small, yet there are enough tools for everyday tasks. However, most of them are in the Javascript world which might not fit into your toolchain and tech stack.

In the next part, we will take a look at RAML and how it solves the documentation problems.