API Blueprint tutorial
Just as Swagger defines a spec for describing a REST API, API Blueprint is another specification for describing REST APIs. If you describe your API with this blueprint, tools that support API Blueprint can read and display the information.
Note that unless you’re using a platform that specifically requires API Blueprint, I recommend using the OpenAPI specification instead.
- What is API Blueprint
- Sample blueprint
- Parsing the blueprint
- Create a sample HTML output using API Blueprint and Apiary
What is API Blueprint
The API Blueprint spec is written in a Markdown-flavored syntax. It’s not regular Markdown, but it has a lot of the same, familiar Markdown syntax. However, the blueprint is a particular schema that is either valid or not valid based on the element names, order, spacing, and other details. In this way, it’s not nearly as flexible or forgiving as Markdown. But it may be preferable to YAML.
Sample blueprint
Here’s a sample blueprint to give you an idea of the syntax:
FORMAT: 1A
HOST: http://polls.apiblueprint.org/
# test
Polls is a simple API allowing consumers to view polls and vote in them.
# Polls API Root [/]
This resource does not have any attributes. Instead, it offers the initial
API affordances in the form of the links in the JSON body.
It is recommended to follow the “url" link values,
[Link](https://tools.ietf.org/html/rfc5988), or Location headers where
applicable to retrieve resources. Instead of constructing your own URLs,
to keep your client decoupled from implementation details.
## Retrieve the Entry Point [GET]
+ Response 200 (application/json)
{
"questions_url": "/questions"
}
## Group Question
Resources related to questions in the API.
## Question [/questions/{question_id}]
A Question object has the following attributes:
+ question
+ published_at - An ISO8601 date when the question was published.
+ url
+ choices - An array of Choice objects.
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
### View a Questions Detail [GET]
+ Response 200 (application/json)
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/1",
"choices": [
{
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}, {
"choice": "Python",
"url": "/questions/1/choices/2",
"votes": 1024
}, {
"choice": "Objective-C",
"url": "/questions/1/choices/3",
"votes": 512
}, {
"choice": "Ruby",
"url": "/questions/1/choices/4",
"votes": 256
}
]
}
## Choice [/questions/{question_id}/choices/{choice_id}]
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
+ choice_id: 1 (required, number) - ID of the Choice in form of an integer
### Vote on a Choice [POST]
This action allows you to vote on a question's choice.
+ Response 201
+ Headers
Location: /questions/1
## Questions Collection [/questions{?page}]
+ Parameters
+ page: 1 (optional, number) - The page of questions to return
### List All Questions [GET]
+ Response 200 (application/json)
+ Headers
Link: </questions?page=2>; rel="next"
+ Body
[
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/1",
"choices": [
{
"choice": "Swift",
"url": "/questions/1/choices/1",
"votes": 2048
}, {
"choice": "Python",
"url": "/questions/1/choices/2",
"votes": 1024
}, {
"choice": "Objective-C",
"url": "/questions/1/choices/3",
"votes": 512
}, {
"choice": "Ruby",
"url": "/questions/1/choices/4",
"votes": 256
}
]
}
]
### Create a New Question [POST]
You may create your own question using this action. It takes a JSON
object containing a question and a collection of answers in the
form of choices.
+ question (string) - The question
+ choices (array[string]) - A collection of choices.
+ Request (application/json)
{
"question": "Favourite programming language?",
"choices": [
"Swift",
"Python",
"Objective-C",
"Ruby"
]
}
+ Response 201 (application/json)
+ Headers
Location: /questions/2
+ Body
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/2",
"choices": [
{
"choice": "Swift",
"url": "/questions/2/choices/1",
"votes": 0
}, {
"choice": "Python",
"url": "/questions/2/choices/2",
"votes": 0
}, {
"choice": "Objective-C",
"url": "/questions/2/choices/3",
"votes": 0
}, {
"choice": "Ruby",
"url": "/questions/2/choices/4",
"votes": 0
}
]
}
For a tutorial on the blueprint syntax, see these resources:
You can find examples of different blueprints here. The examples can often clarify different aspects of the spec.
Parsing the blueprint
Many tools can parse an API blueprint. Drafter is one of the main parsers of the Blueprint. Many other tools build on Drafter and generate static HTML outputs of the blueprint. For example, Aglio can parse a blueprint and generate static HTML files.
