In this article we discuss API Blueprint, what it is, some of it's benefits and how to create your first API specification using API Blueprint.
API Blueprint allows you to blueprint your API. Using your blueprint your team can agree the API’s structure and endpoints before you start development. It’s easy as a developer to jump right in and start building your API, but in my experience it’s vital you get input from the developers who will be using your API. An added bonus is that there are tools available to convert your blueprints to HTML, saving you time writing your API documentation.
Any API developer has probably been in the situation where you’re writing your API documentation in HTML, having to make your way around HTML/CSS. Using API Blueprint avoids this, you’re working with markup only, and tools such as Aglio will generate the HTML/CSS output for you. It’s much more convenient.
Having a Blueprint to work from makes developing an API a much more structured process, you already know what requests your API will receive and what responses the API is expected to return. It’s like building a house from architect plans.
Before we get started, there’s a few things we need to install.
Aglio is a great tool written by Daniel Taylor, use it to parse your API Blueprint and generate HTML output. It handy for those who like to have a physical copy of your API documentation to upload to a web host.
I’m using Mac OS but the installation should be the same for all Linux derived systems, you’ll need to have pre-installed NodeJs (see https://nodejs.org/en/).
Install Aglio from the command line;
$ sudo npm install -g aglio
Upon success installation, check the installation was successful;
$ aglio —version aglio 2.2.0
Install language-api-blueprint Atom plugin
The API Blueprint preview plugin for Atom allows you to view a HTML version of your API documentation as you type, a must have in my opinion. The preview tool uses Aglio which you should have already installed.
You can install the preview plugin either via Atom settings (api-blueprint-preview), or via the command line;
$ apm install api-blueprint-preview