Welcome to an API Blueprint Tutorial! This tutorial will take you through the basics of the API Blueprint language. We’re going to build an API blueprint step by step for a service called Polls – a simple API allowing consumers to view polls and vote in them. You can take a look at the full version of the blueprint used in this tutorial for reference.
Note: Additional API Blueprint Resources
The first step for creating a blueprint is to specify the API Name and metadata. This step looks as follows:
FORMAT: 1A
# Polls
Polls is a simple API allowing consumers to view polls and vote in them.The blueprint starts with a metadata section. In this case we have specified
that FORMAT has the value of 1A. The format keyword denotes the version of
the API Blueprint.
The first heading in the blueprint serves as the name of your API, which in
this case is "Polls". Headings start with one or more # symbols followed by a
title. The API Name here uses one hash to distinguish it as the first level.
The number of # you use will determine the level of the heading.
Following the heading is a description of the API. You may use further headings to break up the description section.
Now it's time to start documenting the API resources. Using the Group keyword
at the start of a heading, we've created a group of related resources.
# Group Questions
Resources related to questions in the API.Within the questions resource group, we have a resource called "Question Collection". This resource allows you to view a list of questions. The heading specifies the URI used to access the resource inside of square brackets at the end of the heading.
## Question Collection [/questions]API Blueprint allows you to specify each action you may make on a resource. An action is specified with a sub-heading inside of a resource with the name of the action followed by the HTTP method.
### List All Questions [GET]An action should include at least one response from the server which must
include a status code and may contain a body. A response is defined as a list
item within an action. Lists are created by preceding list items with either a
+, * or -.
This action returns a 200 status code along with a JSON body.
+ 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
}
]
}
]Note: Specifying the media type after the response status code generates a
Content-TypeHTTP header. You do not have to explicitly specify theContent-Typeheader.
The polls resource has a second action which allows you to create a new question. This action includes a description showing the structure you would send to the server to perform this action.
### 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.This action takes a JSON payload as part of the request as follows:
+ Request (application/json)
{
"question": "Favourite programming language?",
"choices": [
"Swift",
"Python",
"Objective-C",
"Ruby"
]
}This example returns a 201 status code, along with HTTP headers and a body.
+ Response 201 (application/json)
+ Headers
Location: /questions/1
+ 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": 0
}, {
"choice": "Python",
"url": "/questions/1/choices/2",
"votes": 0
}, {
"choice": "Objective-C",
"url": "/questions/1/choices/3",
"votes": 0
}, {
"choice": "Ruby",
"url": "/questions/1/choices/4",
"votes": 0
}
]
}The next resource is “Question”, which represents a single question.
## Question [/questions/{question_id}]The URI for the “Question” resource uses a variable component, expressed by
URI Template. In this case, there is an ID variable called question_id,
represented in the URI template as {question_id}.
URI parameters should describe the URI using a list of Parameters. For “Question” it would be as follows:
+ Parameters
+ question_id (number) - ID of the Question in the form of an integerThe question_id variable of the URI template is a parameter for every action
on this resource. It's defined here using an arbitrary type number, followed
by a description for the parameter.
Refer to API Blueprint Specification's URI Parameters Section for more examples.
This resource has an action to retrieve the question's detail.
### 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
}
]
}This resource has a delete action. The server will return a 204 response without a body.
### Delete [DELETE]
+ Response 204You can find an implementation of this API at http://polls.apiblueprint.org/ along with the complete Poll API Blueprint in the API Blueprint Examples repository. You can also enjoy it rendered on Apiary.
Note: Take a look at the API Blueprint Glossary of Terms if you need clarification of some of the terms used though this document.
Visit the Tooling Section of apiblueprint.org to find tools to use with API Blueprints.