| Author | Version |
|---|---|
z@apiary.io |
1A9 |
- Metadata section
- API name & overview section
- Resource group section
- Resource section
- Resource model section
- Schema section
- Action section
- Request section
- Response section
- URI parameters section
- Attributes section
- Headers section
- Body section
This documents is a full specification of the API Blueprint format. For a less formal introduction to API Blueprint visit the API Blueprint Tutorial or check some of the examples.
API Blueprint is a documentation-oriented web API description language. The API Blueprint is essentially a set of semantic assumptions laid on top of the Markdown syntax used to describe a web API.
In addition to the regular Markdown syntax, API Blueprint conforms to the GitHub Flavored Markdown syntax.
An API Blueprint document – a blueprint – is a plain text Markdown document describing a Web API in whole or in part. The document is structured into logical sections. Each section has its distinctive meaning, content and position in the document.
General section definition and structure is discussed in detail later in the Blueprint section chapter.
All of the blueprint sections are optional. However, when present, a section must follow the API Blueprint document structure.
0-1Metadata section0-1API Name & overview section0+Resource sections0+Resource Group sections0+Resource sections (see above)
0+Data Structures section
NOTE: The number prior to a section name denotes the allowed number of the section occurrences.
NOTE: Refer to Sections Reference for description of a specific section type.
A Section represents a logical unit of an API Blueprint. For example: an API overview, a group of resources or a resource definition.
In general a section is defined using a keyword in a Markdown entity. Depending on the type of section the keyword is written either as a Markdown header entity or in a list item entity.
A section definition may also contain additional variable components such as its identifier and additional modifiers.
NOTE: There are two special sections that are recognized by their position in the document instead of a keyword: The Metadata section and the API Name & Overview section. Refer to the respective section entry for details on its definition.
# <keyword>
...
# <keyword>
...
NOTE: While this specification uses "atx"-style headers (using
#s) you can also use "Setext" header syntax interchangeably:<keyword> ========= ... <keyword> ========= ...
+ <keyword>
...
+ <keyword>
...
NOTE: While this specification uses pluses (
+) as list markers you can use any Markdown list syntax using asterisks (*), pluses (+) and hyphens (-) interchangeably:* <keyword> ... - <keyword> ...
There are several types of API Blueprint sections. You can find the complete listing of the section types in the Section Reference.
The Blueprint section chapter discusses the section syntax in general. A specific section type may conform only to some parts of this general syntax. Always refer for respective section reference for details on its syntax.
A general structure of an API Blueprint section defined by a keyword includes an identifier (name), section description and nested sections or a specifically formatted content.
# <keyword> <identifier>
<description>
<specific content>
<nested sections>
+ <keyword> <identifier>
<description>
<specific content>
<nested sections>
Following reserved keywords are used in section definitions:
GroupData Structures- HTTP methods (e.g.
GET, POST, PUT, DELETE...) - URI templates (e.g.
/resource/{id}) - Combinations of an HTTP method and URI Template (e.g.
GET /resource/{id})
RequestResponseBodySchemaModelHeader&HeadersParameter&ParametersValuesAttribute&AttributesRelation
NOTE: Avoid using these keywords in other Markdown headers or lists
NOTE: With the exception of HTTP methods keywords the section keywords are case insensitive.
A section definition may or must include an identifier of the section.
An identifier is any non-empty combination of any character except [, ],
(, ) and newline characters.
An identifier must not contain any of the keywords.
Adam's Message 42
my-awesome-message_2
A section description is any arbitrary Markdown-formatted content following the section definition.
It is possible to use any Markdown header or list item in a section description as long as it does not clash with any of the reserved keywords.
NOTE: It is considered good practice to keep the header level nested under the actual section.
A section may contain another nested section(s).
Depending on the nested section type, to nest a section simply increase its header level or its list item indentation. Anything between the section start and the start of following section at the same level is considered to be part of the section.
Which sections can be nested and where depends upon the section in case, as described in the relevant section's entry.
# <section definition>
...
## <nested section definition>
...
+ <section definition>
...
+ <nested section definition>
...
NOTE: While not necessary it is a good habit to increase the level of a nested section markdown-header.
NOTE: A markdown-list section is always considered to be nested under the preceding markdown-header section.
NOTE: Sections marked as "Abstract" serve as a base for other sections and as such they cannot be used directly.
- Abstract
- Parent sections: vary, see descendants
- Nested sections: vary, see descendants
- Markdown entity: header, list
- Inherits from: none
Defined by a keyword followed by an optional section name - identifier in a Markdown header or list entity.
# <keyword> <identifier>
+ <keyword> <identifier>
Named section is the base section for most of the API Blueprint sections. It conforms to the general section and as such it is composed of a section name (identifier), description and nested sections or specific formatted content (see descendants descriptions).
# <keyword> Section Name
This the `Section Name` description.
- one
- **two**
- three
<nested sections> | <formatted content>
- Abstract
- Parent sections: vary, see descendants
- Nested sections: none
- Markdown entity: list
- Inherits from: none
Defined by a keyword in Markdown list entity.
+ <keyword>
The asset section is the base section for atomic data in API Blueprint. The content of this section is expected to be a pre-formatted code block.
+ <keyword>
{
"message": "Hello"
}
+ <keyword>
```
{
"message": "Hello"
}
```
- Abstract
- Parent sections: vary, see descendants
- Nested sections:
0-1Headers section,0-1Attributes section,0-1Body section,0-1Schema section - Markdown entity: list
- Inherits from: Named section
Defined by a keyword in Markdown list entity. The keyword may be followed by identifier. The definition may include payload's media-type enclosed in braces.
+ <keyword> <identifier> (<media type>)
NOTE: Refer to descendant for the particular section type definition.
Payload sections represent the information transferred as a payload of an HTTP request or response messages. A Payload consists of optional meta information in the form of HTTP headers and optional content in the form of an HTTP body.
Furthermore, in API Blueprint context, a payload includes its description, description of its message-body attributes and a message-body validation schema.
A payload may have its media type associated. A payload's media type
represents the metadata received or sent in the form of a HTTP Content-Type
header. When specified a payload should include nested
Body section.
This section should include at least one of the following nested sections:
If there is no nested section the content of the payload section is considered as content of the Body section.
Each of body, schema and attributes sections describe a message payload's body. These descriptions should be consistent, not violating each other. When multiple body descriptions are provided they should be prioritized as follows:
-
For resolving message-body schema
- Schema section
- Attributes section
- Body section
-
For resolving message-body example
- Body section
- Attributes section
- Schema section
Instead of providing a payload section content, a model payload section can be referenced using the Markdown implicit reference syntax:
[<identifier>][]
+ <keyword> Payload Name (application/json)
This the `Payload Name` description.
+ Headers
...
+ Body
...
+ Schema
...
+ <keyword> Payload Name
[Resource model identifier][]
- Parent sections: none
- Nested sections: none
- Markdown entity: special
- Inherits from: none
Key-value pairs. Each key is separated from its value by a colon (:). One
pair per line. Starts at the beginning of the document and ends with the first
Markdown element that is not recognized as a key-value pair.
Metadata keys and their values are tool-specific. Refer to relevant tool documentation for the list of supported keys.
FORMAT: 1A
HOST: http://blog.acme.com
- Parent sections: none
- Nested sections: none
- Markdown entity: special, header
- Inherits from: Named section
Defined by the first Markdown header in the blueprint document, unless it represents another section definition.
Name and description of the API
# Basic ACME Blog API
Welcome to the **ACME Blog** API. This API provides access to the **ACME
Blog** service.
- Parent sections: none
- Nested sections:
0+Resource section - Markdown entity: header
- Inherits from: Named section
Defined by the Group keyword followed by group name (identifier):
# Group <identifier>
This section represents a group of resources (Resource Sections). May include one or more nested Resource Sections.
# Group Blog Posts
## Resource 1 [/resource1]
...
# Group Authors
Resources in this groups are related to **ACME Blog** authors.
## Resource 2 [/resource2]
...- Parent sections: none, Resource group section
- Nested sections:
0-1Parameters section,0-1Attributes section,0-1Model section,1+Action section - Markdown entity: header
- Inherits from: Named section
Defined by an URI template:
# <URI template>
-- or --
Defined by a resource name (identifier) followed by an
URI template enclosed in square brackets [].
# <identifier> [<URI template>]
-- or --
Defined by an HTTP request method followed by URI template:
# <HTTP request method> <URI template>
-- or --
Defined by a resource name (identifier) followed by an
HTTP request method and an URI template enclosed
in square brackets []:
# <identifier> [<HTTP request method> <URI template>]
NOTE: In the latter two cases the rest of this section represents the Action section including its description and nested sections and follows the rules of the Action section instead.
An API resource as specified by its URI or a set of resources (a resource template) matching its URI template.
This section should include at least one nested Action section and may include following nested sections:
-
URI parameters defined in the scope of a Resource section apply to any and all nested Action sections except when an URI template has been defined for the Action.
-
Attributes defined in the scope of a Resource section represent Resource attributes. If the resource is defined with a name these attributes may be referenced in Attributes sections.
-
Additional Action sections
NOTE: A blueprint document may contain multiple sections for the same resource (or resource set), as long as their HTTP methods differ. However it is considered good practice to group multiple HTTP methods under one resource (resource set).
# Blog Posts [/posts/{id}]
Resource representing **ACME Blog** posts.# /posts/{id}# GET /posts/{id}- Parent sections: Resource section
- Nested sections: Refer to payload section
- Markdown entity: list
- Inherits from: Payload section
Defined by the Model keyword followed by an optional media type:
+ Model (<media type>)
A resource manifestation - one exemplary representation of the resource in the form of a payload.
The payload defined in this section may be referenced in any response or request section in the document using parent section's identifier. You can refer to this payload in any of the following Request or Response payload sections using the Markdown implicit reference syntax.
# My Resource [/resource]
+ Model (text/plain)
Hello World
## Retrieve My Resource [GET]
+ Response 200
[My Resource][]- Parent sections: Payload section
- Nested sections: none
- Markdown entity: list
- Inherits from: Asset section
Defined by the Schema keyword in Markdown list entity.
+ Schema
Specifies a validation schema for the HTTP message-body of parent payload section.
Following example uses Body section to provide an example of an application/json payload, and Schema section to provide a JSON Schema describing all possible valid shapes of the payload.
## Retrieve a Message [GET]
+ Response 200 (application/json)
+ Body
{"message": "Hello world!"}
+ Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}- Parent sections: Resource section
- Nested sections:
0-1Relation section,0-1URI parameters section,0-1Attributes section,0+Request section,1+Response section - Markdown entity: header
- Inherits from: Named section
Defined by an HTTP request method:
## <HTTP request method>
-- or --
Defined by an action name (identifier) followed by an
HTTP request method enclosed in square brackets [].
## <identifier> [<HTTP request method>]
-- or --
Defined by an action name (identifier) followed by an
HTTP request method and
URI template enclosed in square brackets [].
## <identifier> [<HTTP request method> <URI template>]
Definition of at least one complete HTTP transaction as performed with the parent resource section. An action section may consist of multiple HTTP transaction examples for the given HTTP request method.
This section may include one nested URI parameters section describing any URI parameters specific to the action – URI parameters discussed in the scope of an Action section apply to the respective Action section ONLY.
This section may include one nested Attributes section defining the input (request) attributes of the section. If present, these attributes should be inherited in every Action's Request section unless specified otherwise.
Action section should include at least one nested Response section and may include additional nested Request and Response sections.
Nested Request and Response sections may be ordered into groups where each group represents one transaction example. The first transaction example group starts with the first nested Request or Response section. Subsequent groups start with the first nested Request section following a Response section.
Multiple Request and Response nested sections within one transaction example should have different identifiers.
# Blog Posts [/posts{?limit}]
...
## Retrieve Blog Posts [GET]
Retrieves the list of **ACME Blog** posts.
+ Parameters
+ limit (optional, number) ... Maximum number of posts to retrieve
+ Response 200
...
## Create a Post [POST]
+ Attributes
...
+ Request
...
+ Response 201
...
## Delete a Post [DELETE /posts/{id}]
+ Parameters
+ id (string) ... Id of the post
+ Response 204# Resource [/resource]
## Create Resource [POST]
+ request A
...
+ response 200
...
+ request B
...
+ response 200
...
+ response 500
...
+ request C
...
+ request D
...
+ response 200
...NOTE: The "Multiple Transaction Examples" example demonstrates three transaction examples for one given action:
- 1st example: request
A, response200- 2nd example: request
B, responses200and500- 3rd example: requests
CandD, response200
- Parent sections: Action section
- Nested sections: Refer to payload section
- Markdown entity: list
- Inherits from: Payload section
Defined by the Request keyword followed by an optional identifier:
+ Request <identifier> (<Media Type>)
One HTTP request-message example – payload.
+ Request Create Blog Post (application/json)
{ "message" : "Hello World." }- Parent sections: Action section
- Nested sections: Refer to payload section
- Markdown entity: list
- Inherits from: Payload section
Defined by the Response keyword. The response section definition should
include an HTTP status code as its identifier.
+ Response <HTTP status code> (<Media Type>)
One HTTP response-message example – payload.
+ Response 201 (application/json)
{ "message" : "created" }- Parent Sections: Resource section | Action section
- Nested Sections: none
- Markdown entity: list
- Inherits from: none, special
Defined by the Parameters keyword written in a Markdown list item:
+ Parameters
Discussion of URI parameters in the scope of the parent section.
This section must be composed of nested list items only. This section must not contain any other elements. Each list item describes a single URI parameter. The nested list items subsections inherit from the Named section and are subject to additional formatting as follows:
+ <parameter name>: `<example value>` (<type> | enum[<type>], required | optional) - <description>
<additional description>
+ Default: `<default value>`
+ Members
+ `<enumeration value 1>`
+ `<enumeration value 2>`
...
+ `<enumeration value N>`
Where:
<parameter name>is the parameter name as written in Resource Section's URI (e.g. "id").<description>is any optional Markdown-formatted description of the parameter.<additional description>is any additional optional Markdown-formatted description of the parameter.<default value>is an optional default value of the parameter – a value that is used when no value is explicitly set (optional parameters only).<example value>is an optional example value of the parameter (e.g.1234).<type>is the optional parameter type as expected by the API (e.g. "number", "string", "boolean"). "string" is the default.Membersis the optional enumeration of possible values.<type>should be surrounded byenum[]if this is present. For example, if enumeration values are present for a parameter whose type isnumber, thenenum[number]should be used instead ofnumberto.<enumeration value n>represents an element of enumeration type.requiredis the optional specifier of a required parameter (this is the default)optionalis the optional specifier of an optional parameter.
NOTE: This section should only contain parameters that are specified in the parent's resource URI template, and does not have to list every URI parameter.
# GET /posts/{id}+ Parameters
+ id - Id of a post.+ Parameters
+ id (number) - Id of a post.+ Parameters
+ id: `1001` (number, required) - Id of a post.+ Parameters
+ id: `1001` (number, optional) - Id of a post.
+ Default: `20`+ Parameters
+ id (enum[string])
Id of a Post
+ Members
+ `A`
+ `B`
+ `C`- Parent sections: Resource section | Action section | Payload section
- Nested sections: See Markdown Syntax for Object Notation
- Markdown entity: list
- Inherits from: none
Defined by the Attributes keyword followed by an optional
MSON Type Definition enclosed in parentheses.
+ Attributes <Type Definition>
<Type Definition> is the type definition of the data structure being
described. If the <Type Definition> is not specified, an object base type
is assumed. See MSON Type Definition for details.
+ Attributes (object)This section describes a data structure using the Markdown Syntax for Object Notation (MSON). Based on the parent section, the data structure being described is one of the following:
- Resource data structure attributes (Resource section)
- Action request attributes (Action section)
- Payload message-body attributes (Payload section)
Data structures defined in this section may refer to any arbitrary data structures defined in the Data Structures section as well as to any data structures defined by a named resource attributes description (see below).
Description of the resource data structure.
If defined in a named Resource section, this data structure may be referenced by other data structures using the resource name.
# Blog Post [/posts/{id}]
Resource representing **ACME Blog** posts.
+ Attributes
+ id (number)
+ message (string) - The blog post article
+ author: john@appleseed.com (string) - Author of the blog postNOTE: This data structure can be later referred as:
+ Attributes (Blog Post)
Description of the default request message-body data structure.
If defined, all the Request sections of the respective Action section inherits these attributes unless specified otherwise.
## Create a Post [POST]
+ Attributes
+ message (string) - The blog post article
+ author: john@appleseed.com (string) - Author of the blog post
+ Request (application/json)
+ Request (application/yaml)
+ Response 201Description of payload (request, response, model) message-body attributes.
Not every attribute has to be described. However, when an attribute is described, it should appear in the respective Body section example, if a Body section is provided.
If defined, the Body section may be omitted and the example representation should be generated from the attributes description.
The description of message-body attributes may be used to describe message-body validation if no Schema section is provided. When a Schema section is provided, the attributes description should conform to the schema.
## Retrieve a Post [GET]
+ Response 200 (application/json)
+ Attributes (object)
+ message (string) - Message to the world
+ Body
{ "message" : "Hello World." }- Parent sections: Payload section
- Nested sections: none
- Markdown entity: list
- Inherits from: none
Defined by the Headers keyword in Markdown list entity.
+ Headers
Specifies the HTTP message-headers of the parent payload section. The content this section is expected to be a pre-formatted code block with the following syntax:
<HTTP header name>: <value>
One HTTP header per line.
+ Headers
Accept-Charset: utf-8
Connection: keep-alive
Content-Type: multipart/form-data, boundary=AaB03x- Parent sections: Payload section
- Nested sections: none
- Markdown entity: list
- Inherits from: Asset section
Defined by the Body keyword in Markdown list entity.
+ Body
Specifies the HTTP message-body of a payload section.
+ Body
{
"message": "Hello"
}- Parent sections: none
- Nested sections: MSON Named Type definition (see below)
- Markdown entity: header
- Inherits from: none
Defined by the Data Structures keyword.
# Data Structures
This section holds arbitrary data structures definitions defined in the form of MSON Named Types.
Data structures defined in this section may be used in any Attributes section. Similarly, any data structures defined in a Attributes section of a named Resource Section may be used in a data structure definition.
Refer to the MSON specification for full details on how to define an MSON Named type.
# Data Structures
## Message (object)
+ text (string) - text of the message
+ author (Author) - author of the message
## Author (object)
+ name: John
+ email: john@appleseed.com# User [/user]
+ Attributes (Author)
# Data Structures
## Author (object)
+ name: John
+ email: john@appleseed.com# User [/user]
+ Attributes
+ name: John
+ email: john@appleseed.com
# Data Structures
## Author (User)- Parent sections: Action section
- Nested Sections: none
- Markdown entity: list
- Inherits from: none
Defined by the Relation keyword written in a Markdown list item followed by a
colon (:) and a link relation identifier.
+ Relation: <link relation identifier>
This section specifies a link relation type for the given action as specified by RFC 5988.
NOTE: The link relation identifiers should be unique per resource in the blueprint document.
# Task [/tasks/{id}]
+ Parameters
+ id
## Retrieve Task [GET]
+ Relation: task
+ Response 200
{ ... }
## Delete Task [DELETE]
+ Relation: delete
+ Response 204The API Blueprint uses a subset of RFC6570 to define a resource URI Template.
At its simplest form – without any variables – a path segment of an URI Template is identical to an URI path segment:
/path/to/resources/42
Variable names are case-sensitive. The variable name may consists of following characters only:
- ASCII alpha numeric characters (
a-z,A-Z) - Decimal digits (
0-9) _- Percent-encoded characters
.
Multiple variables are separated by the comma without any leading or
trailing spaces. A variable(s) must be enclosed in braces – {}
without any additional leading or trailing whitespace.
The first variable in the braces might be preceded by an operator. API Blueprint currently supports the following operators:
#– fragment identifier operator+– reserved value operator?– form-style query operator&– form-style query continuation operator
{var}
{var1,var2,var3}
{#var}
{+var}
{?var}
{?var1,var2}
{?%24var}
{&var}
NOTE: The explode variable modifier is also supported. Refer to RFC6570 for its description.
Following characters are reserved in variable values:
: / / / ? / # / [ / ] / @ / ! / $ / & / ' / ( / ) / * / + / , / ; / =
Simple path segment component variable is defined without any operator:
/path/to/resources/{var}
With var := 42 the expansion is /path/to/resources/42.
NOTE: RFC6570 – Level 1
URI Template variables for fragment identifiers are defined using the
crosshatch (#) operator:
/path/to/resources/42{#var}
With var := my_id the expansion is /path/to/resources/42#my_id.
NOTE: RFC6570 – Level 2
To define URI Template variables with reserved URI characters,
use the plus (+) operator:
/path/{+var}/42
With var := to/resources the expansion is /path/to/resources/42.
NOTE: RFC6570 – Level 2
To define variables for a form-style query use the question mark (?) operator
/path/to/resources/{varone}{?vartwo}
With varone := 42 and vartwo = hello the expansion is /path/to/resources/42?vartwo=hello.
To continue a form-style query use the ampersand (&) operator:
/path/to/resources/{varone}?path=test{&vartwo,varthree}
With varone := 42, vartwo = hello, varthree = 1024 the expansion is /path/to/resources/42?path=test&vartwo=hello&varthree=1024.
NOTE: RFC6570 – Part of Level 3