API Blueprint Anatomy

On the left is the basic structure of an API 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 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.

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

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 inhere too.

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.

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.