API Blueprint¶
API Blueprint is a high-level language for describing web APIs. The syntax is a combination of Markdown syntax and Markdown Syntax for Object Notation (MSON), and the files are saved with a .apib extension. Markdown is a lightweight text formatting syntax. MSON is an extension of Markdown for describing data objects.
The goal of the API Blueprint format is to support the design-first philosophy for REST APIs; however, the format works just as well for documenting existing APIs.
Getting started¶
The quickest way to get started is to use Apiary to edit and view your documentation. Apiary is a service that allows you to edit and host documentation online. Start by signing up for an account on Apiary. Next, continue with the API Blueprint Tutorial. It provides a good overview of how to describe a basic API.
Writing docs¶
The structure for an .apib file is:
Metadata
API Name
Resource Group
Resource
Action
Action
Resource
Resource Group
Data Structures
Metadata:- describes the API Blueprint version
API Name:- is your API name
Resource Groups:- describes a collection of related API endpoints
Resources:- describes a specific API endpoint
Actions:- describes specific http verb actions to an endpoint
Data Structures:- describes data used in your API requests/responses. By defining them in a separate section, they can easily be reused.
Building docs¶
The two most popular tools for generating documents from API Blueprints are Apiary and Aglio.
- Building docs with Apiary.
