Apiary

    Go to Navigation

API Blueprint Tutorial

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

API Blueprint

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.

Metadata

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.

API Name & Description

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.

Resource Groups

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

Resource related to questions in the API.

Resource

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]

Actions

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 responses 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 explicitly specify the Content-Type header.

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

URI Template

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

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 form of an integer

The 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.

Actions

This resource has an action to retrieve the questions 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
                    }
                ]
            }

Response Without a Body

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

### Delete [DELETE]

+ Response 204

Complete Blueprint

You 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.

API Blueprint Tools

Visit the Tooling Section of apiblueprint.org to find tools to use with API Blueprints.

* For legacy Apiary blueprint syntax help click here

Apiary Blueprint syntax (legacy) explained

At Apiary we try hard to be as user-friendly to developers as possible. Instead of forcing you to click through a confusing GUI, we designed Apiary around API Blueprint—a custom DSL (domain-specific language) allowing you to quickly describe your API in a way that you can collaborate/version/merge as you're used to when coding. From this API Blueprint we then generate API documentation, a mock server (prototype), a debugging proxy and bug reports.

Looking for the New API Blueprint? Visit the apiblueprint.org or go directly to the API Blueprint Tutorial.

Hover a section → its description will appear. Click a section → the description will stay open.

HOST: http://www.google.com/
      
--- Sample API v2 ---
---
Welcome to our API. Comments support [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax
---

-- Shopping Cart Resources --

List products in your shopping cart. Contains product IDs, quantity and other useful informations.
GET /shopping-cart
> Accept: application/json
< 200
< Content-Type: application/json
{ "items": [
  { "url": "/shopping-cart/1", "product":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 }
] }

Apiary Blueprint Anatomy

On the left is the basic structure of an Apiary Blueprint.
Click on individual sections to display more info.

  • Your API consists of a list of resources, separated by two empty lines
  • Resources can optionally be grouped into sections
  • Resources, sections and the whole API may optionally have descriptions, written in Markdown
  • Each resource must contain the HTTP method, URL and HTTP response status code
  • Resources can also have incoming/outgoing HTTP headers and incoming/outgoing data—all of which is optional

API Server Hostname optional

This header specifies the address of the real API server (if available).

If present, you'll be able to switch the Apiary mock server to a transparent HTTP proxy instead (in Settings section). This way, we send all requests to your real API server and compare both the requests and responses to the API documentation.

You can either enter a full URL (HOST: http://example.com/) or just the hostname (HOST: example.com)

Tip: If you include a path in the URL (HOST: http://example.com/v2) we'll use this path as a prefix to the whole API documentation. This way, you can easily version your API or re-base it to different API roots if you need to.

API Documentation Title required

This is the top level title for your API. It's in the web page <title> and also displayed in the documentation.

Note: Make sure to include a space between the --- characters and the title text.

Api Title

API Documentation Description optional

This is the right place to mention the common rules that all your API resources follow. Expected formats, authentication requirements etc.

Tip: You can use Markdown syntax.

Api Description

Section optional

You can group multiple connected resources into a section. A section has its own name and description, and if you use sections, your documentation will have a table-of-contents to speed up navigation on the page.

Note: Make sure to include a space between the -- characters and the title text.

Tip: You can also include description of your section on a second line, using the following syntax:

--
Section Name
A longer section description using Markdown
--
Section Title

Resource Description optional

This will be rendered just below the Resource Signature (highlighted).

It can be either short textual description of this specific resource (oneliner note) or a more sophisticated description using advanced Markdown techniques (lists, tables, blockquotes, …)

Tip: You can use Markdown syntax here as well.

Resource Signature

Resource required

HTTP method and URL of a resource.

Note:

If you need support for "parameters", you may use /url/{parameters} or /query{?string,arguments} syntax as per RFC 6570. See our documentation.

Resource Signature

HTTP Status Code required

This is the numeric HTTP Status Code that is expected from this resource. This must be the first line prefixed with < . Any further lines with the same prefix are treated as response headers.

Codes used:

  • 2xx for success
  • 3xx for redirection
  • 4xx for client error
  • 5xx for server error

See W3C for more details.

Request/Response Headers optional

HTTP headers to be returned from the resource (e.g. Content-Type, Set-Cookies etc). Each line has to start with the character > for request headers or < for response headers (note the required space behind the angle bracket).

In many cases, you'll be returning non-essential headers as well, possibly added automatically by your HTTP server or a HTTP proxy. Document only headers relevant to your API.

Note: The header keys are compared case-insensitive (see the RFC).

Pro Tip: Apiary looks for Content-Type header in your response. If present, it uses it to guess how to syntax-highlight your response body (in the next section).

Response Body optional

The data returned by the resource. Use an example that illustrates well a typical scenario. If your response HTTP headers specify a Content-Type of either application/json or text/xml, then the data will be appropriately syntax-highlighted. XML must begin with the characters <X where X is not a space (otherwise it's parsed as an incoming header).

Note: Two empty lines are required to separate the next resource.

Diff Mechanics

Your incoming HTTP requests will be compared to this data with a text diff, on a line-by-line basis. The real data passing to the API might often be different (different IDs, timestamps, names etc.) and will show up as differences to the documentation. Most programmers can understand if the difference is significant or not.

Tip: We have preliminary support for the JSON Schema, used to describe JSON data structures and are considering adding RelaxNG support. Using these grammars, you can specify required and optional fields, data types, regular expressions used to validate values etc. Let us know if you need this.