API Specification – API Blueprint

What’s an API Blueprint?

An API Blueprint is actually a specification used to describe an API. Its source is a markdown file using plain text formatting. The specification enables a software developer/architect/whatever to use their documents with other applications/tools that adhere to the same specification.

What’s so special about using a specification?

You actually create a document based on a specification. This way, both humans and software can read it. Since it follows a common format/structure, software can parse these documents and use the contents. The contents can be used for some things such as documentation and mock servers.

Why bother making an API Blueprint?

It may seem like it’s just a lot of additional work, but it can save development time drastically. Real example, I had introduced this blueprint idea at work and decided to go ahead and build it. I had not even started programming this API yet but I created the blueprint for what my fellow coworker and I agreed on should be included in the API.

From this, I used a NodeJS tool called Drakov to create a mock server. While I was busy working on a separate application. My coworker was able to program his application using the mock server just like he would a server in production. The responses can be somewhat limited, but can easily be modified.

Not only was this great because he didn’t need to wait for me to program the API for his testing. But we found changes that needed to be made to the API for his application to function as desired. We were able to make a solid API design without rewriting any parts of the API while the client application was being built.

Documentation was mentioned…

Yes, the documentation aspect is wonderful. I think source documentation is underrated, but API documentation is a necessity. I used a tool called aglio to generate documentation for the API. Using the same markdown file (API Blueprint) created for the mock server, aglio generates its documentation. Check this example out from aglio below.

API Blueprint aglio example

This is the cyborg theme which looks pretty cool IMO. In the generating of the documentation, no html is needed. You can however use HTML to manipulate the icons and some styles.

Another thing worth mentioning. When using aglio to generate the documentation, it will also generate the response schema. This is a description of the object being returned. You can also use this schema to validate your json responses, also in unit testing! I’ll get to that another time…

I hope you found this post informative! If you have any tools you’d like to share please leave a comment. Maybe even a new parser or theme for API documentation, please share.