The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
- Overview
- Goals
- Blueprint Template
- 3.1. Metadata
- 3.2. API Name
- 3.3. Resource Groups
- 3.4. Resources
- 3.5. Actions
- 3.6. Attributes
- 3.7. Resource model
- 3.8. Data attributes
- Segregation
- 4.1. Hercule
- 4.2. Example
- 4.3. Transclusion
- Versioning
- 5.1. Hercule
- Testing
- Generate Documentation
- 7.1. Aglio
- 7.2. Apiary CLI
- Cheat sheet
- 8.1. Hercule
- 8.2. Aglio
- 8.3. Apiary CLI
- 8.4. Dredd
- References
API Blueprint is a documentation-oriented API description language in pure markdown.
API Blueprint is great for designing a Web API and its comprehensive documentation but also for quick prototyping and collaboration.
- Have a human editable and readable documentation format
- Generate HTML documentation automatically
- Validate API documentation
API Blueprint MUST have some metadata at the beginning of the markdown file.
FORMAT: 1A
We MUST use format 1A.
Right after the format definition we MUST specify the API name and its description.
FORMAT: 1A
# Message JSON-RPC API
Description of Message API.
The description MAY be as verbose as we like. For example we can create a section with the error format what our API returns when an error occurs.
In an API there are various resources such as Messages, Users or Orders. In our blueprint we MAY gather the related resources into groups.
FORMAT: 1A
# Message API
Description of Message JSON-RPC API.
# Group Messages
# Group Users
# Group Orders
Resource Groups are OPTIONAL but RECOMMENDED as they make the API documentation more structured and more readable.
In the example below there are two resources, Public and Direct Messages within the Messages resource group.
It is RECOMMENDED to specify all the resources individually what we have as it makes our blueprint more descriptive.
FORMAT: 1A
# Message API
Description of Message JSON-RPC API.
# Group Messages
## Public Messages [/json-rpc/v1]
## Direct Messages [/json-rpc/v1]
We MUST describe the resource URI endpoint on all of the resources between a [].
API Blueprint allows we to specify each action we MAY make on a resource.
An action SHOULD include at least one response from the server which MUST include a status code and MAY contain a body.
FORMAT: 1A
# Message API
Description of Message JSON-RPC API.
# Group Messages
## Public Messages [/json-rpc/v1]
### Get Welcome Message [POST]
Description of Get Welcome Message.
+ Request Get Welcome Message (application/json)
{
"jsonrpc": "2.0",
"id": 1,
"method": "getWelcomeMessage"
}
+ Response 200 (application/json)
{
"jsonrpc": "2.0",
"id": 1,
"result": "Welcome"
}
With attributes we can describe the schema of a request (or response) body.
We SHOULD describe all body attributes of a request and response message.
+ Request Get Welcome Message (application/json)
+ Attributes (object)
+ jsonrpc: 2.0 (enum, fixed) - A description
+ id: 1 (number, required)
I can write a longer description here
+ params (object, required)
+ name: adamTheDeveloper (string, required)
+ method: getInternalMessages (string, fixed)
+ Body
{
"jsonrpc": "2.0",
"id": 1,
"params": {
"name": "adamTheDeveloper"
},
"method": "getInternalMessages"
}
MSON (Markdown Syntax for Object Notation) is the description format we MUST apply. It is compatible with JSON and JSON Schema.
Resource model is a resource manifestation. One particular representation of your resource.
Any resource model you have defined MAY be referenced in a request or response section, saving you lots of time maintaining your API blueprint.
# My Resource [/resource]
+ Model (text/plain)
Hello World
## Retrieve My Resource [GET]
+ Response 200
[My Resource][]
This section holds arbitrary data structures definitions defined in the form of MSON Named Types.
Data structures defined in data attributes section MAY be used in any Attributes section.
# User [/user]
+ Attributes (Author)
# Data Structures
## Author (object)
+ name: Hawking
+ email: [email protected]
It is RECOMMENDED to put our data structures definitions at the end of our blueprint.
The more features an API has, the longer it takes to edit its blueprint.
So it is RECOMMENDED to separate our blueprints logically (by API resources or API methods...).
{root-directory-of-the-api-application}
`-- blueprints
`-- resources
| |-- user.md
| |-- users.md
| |-- product.md
| |-- products.md
| |-- order.md
| `-- orders.md
`-- blueprint.md
It is RECOMMENDED to separate these components:
- Resources
- Methods
- Resource models
- Data structures
We need a tool for blueprint segregation and this tool is Hercule.
Hercule is a Markdown Transclusion Tool.
Hercule is a command-line tool for transcluding markdown documents, including API documentation written in API Blueprint format. With Hercule you can easily break complex documents into smaller logical documents, preventing repetition and improving consistency.
We can simply include any blueprint into our markdown by relative paths.
Suppose that we edit blueprints/blueprint.md and we want to include blueprints/resources/user.md and blueprints/resources/users.md.
FORMAT: 1A
# Awesome Api
Description of Awesome API.
# Group User
:[](resources/user.md)
:[](resources/users.md)
It is RECOMMENDED to do the transclusion this way:
hercule blueprints/blueprint.md -o blueprint.md
We are in the root of our repository.
Our API MAY evolve so its Blueprint so we SHOULD keep the API Blueprint file in the repo of its API.
It is RECOMMENDED to save the blueprint file as a blueprint.md in the root of the API repo.
{root-directory-of-the-api-application}
`-- blueprint.md
We MAY support more than one API version, so we MUST keep all the supported API documentations in our repository.
{root-directory-of-the-api-application}
|-- blueprint-v1.md
|-- blueprint-v2.md
`-- blueprint-v3.md
It is RECOMMENDED to remove all the unsupported API documentations from the repo.
If we break our documentation into smaller parts with Hercule we SHOULD follow the structure below.
{root-directory-of-the-api-application}
`-- blueprints-v1
| `-- resources
| | |-- user.md
| `-- blueprint.md
`-- blueprints-v2
| `-- resources
| | |-- user.md
| `-- blueprint.md
As an API evolves so its blueprint. This means we SHOULD test the blueprint file againts the actual API implementation.
Dredd is able to validate an API Documentation.
Dredd is a very simple tool, it sends the exact request what appears in the blueprint and expects the same response what described for that request. It means we MUST create separated fixtures (seeds) especially for Dredd.
API Blueprint is a pure markdown format. We can render the blueprint in a markdown viewer but result won't be an easily readable API documentation. This is why we SHOULD use a documentation generator tool for API Blueprint to create a readable and structured documentation for humans.
Aglio is a API Blueprint renderer that supports multiple themes and outputs static HTML that can be served by any web host.
Pros:
- multi page documentations
- highly human readable documentation
- fancy design
Cons:
- not an official apiary product
- newest blueprint features?
- bug fixes?
- Data attributes feature does not supported, but the support is planned
The Apiary CLI gem is a command line tool for developing and previewing API Blueprint documents locally.
Pros:
- official apiary product
- up to date against the newest blueprint features
- Data attributes feature supported, but not formatted in the documentation
Cons:
- single page documentation
- harder navigation through the documentation page
- not so shiny web interface
hercule source.md -o destination.md
aglio -t default-multi -i source.md -o destination.html
apiary preview --path=source.md --output=destination.html
dredd source.md http://localhost/api-endpoint