API Blueprint describes itself as a powerful high-level API description language for web APIs. It’s a opensource project with MIT license that focuses on collaboration and encourages better API designs through abstraction.
For any API-first design, the main goal is to design the API on not focusing on the backend implementation behaviour. Designing your API first is like settling a contract before it is developed, which leads to better designs.
So the API Blueprint is like a design language and there are lots of tools available to design the same thing following a specification.
Developing with Aglio
Aglio is an API Blueprint renderer with theme support that outputs static HTML. It compiles a markdown file with API Blueprint standards.
Let’s start using it.
Let’s create a folder
aglio-test to start tinkering with our API design process and create a
package.json file to put down the dependencies.
"description": "Test API with Aglio",
"dev": "aglio --theme-full-width --theme-template triple --theme-variables slate -i docs.md -s",
"build": "aglio --theme-full-width --theme-template triple --theme-variables slate -i docs.md -o index.html"
"author": "Tareq Hasan <firstname.lastname@example.org",
Here I’m using two npm scripts to parse and generate the documentation. These two are just few ready-made commanline parameters to get started by. It actually instructs Aglio that what theme we want to use and which file to parse.
There are few themes available for use.
After you’ve created the
package.json following the one above, let’s install the dependencies:
All the dependencies will be installed.
As described in the npm scripts, we are using a
docs.md file to write all our docs. Aglio will turn the markdown into pretty API docs file.
The standard file starts with a FORMAT metadata identifying the version of API Blueprint and the HOST as your API endpoint URL.
I’m not going into more details and docs for API Blueprint as it’s already available in their site.
While developing with documentation, you can watch for changes and aglio will build the preview on-the-fly. Just run:
npm run dev
It’ll open a local server and will monitor the changes. Once you do any changes, will be reflected on the browser.
After you finish developing, you can run:
npm run build
Aglio will parse the
docs.md file and generate a
index.html as specified in the npm scripts. You can deploy the file in a domain somewhere to publish your API documentation.