This tutorial will take you through the basics of the API Blueprint language. We’re going to build an API Blueprint step by step.

API Blueprint logo

API Blueprint

API Blueprint is open sourced format for describing APIs.

This is how API Blueprint looks like:

FORMAT: 1A

# Polls

Polls is a simple API allowing consumers to view polls and vote in them.

## Questions Collection [/questions]

### List All Questions [GET]

+ Response 200 (application/json)

        {
            "question": "Favourite programming language?",
            "choices": [
                {
                    "choice": "Swift",
                    "votes": 2048
                }, {
                    "choice": "Python",
                    "votes": 1024
                }
            ]
        }
Note

Recommended file extension for API Blueprint is .apib

Writing API Blueprint

Choosing editor

If you are new to API Blueprint, best choice is to use Apiary Editor on Apiary.io, because of its built-in helpers and instant preview.

Metadata, API Name & Description

The first step for creating a Blueprint is to specify the API Name and metadata:

FORMAT: 1A

# Polls

Polls is a simple API allowing consumers to view polls and vote in them.

The Blueprint starts with a metadata section. The FORMAT keyword is required and denotes that document is API Blueprint.

Note

You can also add HOST, which should have value of your production API URI. This will allow you to test and debug production calls from Apiary.

First level heading # Polls will become API name.

Resource

API consists of resources specified by their URIs. In this example we have a resource called Question Collection, which allows you to view a list of questions. The heading specifies its URI inside of square brackets [/questions].

## Question Collection [/questions]

Actions

You should specify each action you may make on a resource. An action is specified with a sub-heading with the name of the action followed by the HTTP method.

## Question Collection [/questions]

### 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-Type HTTP header. You do not have to specify it manually in Headers section.

The polls resource has a second action which allows you to create a new question. This action shows the structure you should send to the server to perform this action.

### Create a New Question [POST]
You may create your own question using this action.
This action takes a JSON payload as part of the request.
Response then return specific header and body.

+ Request (application/json)

        {
            "question": "Favourite programming language?",
            "choices": [
                "Swift",
                "Python",
                "Objective-C",
                "Ruby"
            ]
        }

+ 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
                    }
                ]
            }

Single resource with parameters

The next resource is Question, which represents a single question.

## Question [/questions/{question_id}]

+ Parameters
    + question_id (number) - ID of the Question in the form of an integer
URI Template

The URI for the Question resource uses a variable component {question_id}, expressed by URI Template.

URI Parameters

URI parameters + Parameters should describe the URI using a list of Parameters.

The question_id variable of the URI template is a parameter for every action on this resource. Here it’s defined as type number, followed by its description.

With action:

## Question [/questions/{question_id}]

+ Parameters
    + question_id (number) - ID of the Question in the 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
                }
            ]
        }

Once you add this Blueprint into Apiary, you will instantly get a Mock server, Traffic inspector, Interactive console and much more for your API.

Advanced usage

Resource Groups

You can group related resources by using heading with the Group keyword.

FORMAT: 1A

# Polls

Polls is a simple API allowing consumers to view polls and vote in them.

# Group Questions

Resources related to questions in the API.

Response Without a Body

This resource has a delete action. The server will return a 204 response without a body.

## Question [/questions/{question_id}]

+ Parameters
    + question_id (number) - ID of the Question in the form of an integer

### Delete [DELETE]

+ Response 204

Multiple responses

You can specify different responses and even different requests on each action. Multiple responses are supported within Mock server. It is especially suitable for handling multiple types of Content-Type header.

### Retrieve Message [GET]
+ Request
    + Headers

            Authorization: Basic ABCDEF

+ Response 200 (application/json)

        {
            "message":"Hello World!"
        }

+ Request (application/json)
    + Body

            {
               "grant_type": "client_credentials"
            }

+ Response 401 (text/plain)

        There is no such a message for you, dear guest.

+ Response 410 (text/plain)

        The message you are searching for does not exist anymore.
Note

If you are responding differently based on parameters/query string arguments, you should use URI templates.

Further reading