API Blueprint is a high level language for describe web APIs. The syntax is a combination of Markdown and MSON syntax 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 enable the design-first philosophy for REST APIs, however, the format works just as well for documenting existing APIs.
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.
The structure for an
.apib file is:
Metadata API Name Resource Group Resource Action Action Resource Resource Group Data Structures
- describes the API Blueprint version
- is your API name
- describes a collection of related API endpoints
- describes a specific API endpoint
- describes specific http verb actions to an endpoint
- describes data used in your API requests/responses. By defining them in a separate section, they can easily be reused.