API Blueprint: Markdown is awesome!
In the last post, I talked about API-First, and I showed an API specification written using Swagger (OpenApi Specification).
There is another cool player in the market, we are talking about the API Blueprint, and today’s post is about this practical tool.
The smallest learning curve in the west
A former colleague, a long time ago, showed me the API Blueprint. From his point of view, one of the most exciting aspects of it was writing using Markdown.
Yes! It’s true! Of course, using a specific format/extension brings benefits like syntax highlighting. However, it’s still possible to write the API specification using only Markdown, which makes its reading more natural, and interoperable with other tools like your text editor, or Github itself.
If you already have a README.md file, having an api.md one, doesn’t look like a big deal. Also, depending on your stakeholders, having a “final documentation” might be as simple as sharing a Github link.
But what’s API Blueprint after all?
The official documentation defines it as:
(…) 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.
Like the already cited Swagger, the API Blueprint is a design language used to describe APIs. It encourages dialog and collaboration, ending with an ideal tool to have while adopting the API-First process.
To have the benefits mentioned before, the API Blueprint uses an “enhancement” of Markdown called MSON (Markdown Syntax for Object Notation). Is using this notation that we can describe data structures, inheritances, and resources with Markdown.
Getting started
Let’s describe a movie API, starting with an api.md file.
The begin with, we need to tell which API Blueprint version we are going to use. Also, we need to describe the API purpose:
FORMAT: A1
# Movies API
This is an API Blueprint example describing a movies API.The #, in Markdown, means “header level 1”. In other words, the # Movies API if converted to HTML produce a <h1>Movies API</h1>. In that case, the # produces the API title. The # is also used to group resources, but the use of the keyword Group is needed:
FORMAT: A1
# Movies API
This is an API Blueprint example describing a movies API.
# Group Movies
Resources related to movies in the API.Describing resources
The next step is to describe the resource and its endpoints. Starting by the endpoint /movies. To describe the resource, we use the ##, and the action is described through the use of ###:
(...)
## Movie collection [/movies]
### List all Movies [GET]
List movies in reverse order of publication.
+ Response 200 (application/json)When the resource /movies receive a GET request, it will answer with a 200 status code, and with the content-type of application/json. This last part is described through line + Response 200 (application/json).
We can also describe how the response payload is going to be.
Describing the data
It’s possible to use JSON Schema to describe the request and response payloads. It’s a powerful vocabulary to annotate and validate JSON documents. However, it might be hard to read.
There is an alternative using MSON. Through the use of ## Data structure section, we can use a special syntax to describe the payload.
(...)
## Data structures
### Movie
+ id: 810b43d0-fc0d-4199-8a79-25b471c880bf (string, required)
+ title: Avengers: Endgame (string, required)
+ description (string)The Movie structure has an id (string and required), title and description. Note that the last one. is not required and doesn’t have an example.
To bind the structure above with the answer of /movies, we use Attributes:
(...)
### List all Movies [GET]
List movies in reverse order of publication.
+ Response 200 (application/json)
+ Attributes (array[Movie])
(...)With the type array, we are now done with the payload description.
Check the API Blueprint tutorial to learn how to apply the specification to the other HTTP verbs.
You can see the complete example here.
The images used to show the specification working are from the VS Code plugin called API Blueprint Viewer.
Conclusion
In the API Blueprint oficial site you can see different tools available, from text editors to mock servers.
One of the coolest tools you’re going to find there is Dredd, which is a spec validator, and works with API Blueprint and OpenAPI Specification. By the way, OpenApi/Swagger are still the “champions” when the subject is ecosystem.
Writing API Blueprint with Markdown is easy, and turn the tool in an interesting option while describing REST APIs.
See you next time.
This post was originally written in Brazilian Portuguese for klauslaube.com.br.
