1.3 3. API Blueprint document

An API Blueprint document – a blueprint is a plain text Markdown document describing a Web API or its 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.

1.4 4. Blueprint section

Section represents a logical unit of 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.

1.4.0.1 Example: Header-defined sections

# <keyword>
...
# <keyword>
...

NOTE: While this specification uses “atx” -style headers (using #s) you can also use “Setext” header syntax interchangeably:

<keyword>
=========
...
<keyword>
=========
...

1.4.0.2 Example: List-defined sections

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

1.4.1 4.1 Section types

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.

1.4.2 4.2 Section structure

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.

1.4.4.1 Example

1.4.5 4.5 Description

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.

1.4.6 4.6 Nested sections

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.

What sections can be nested and where depends upon the section in case, as described in the relevant section’s entry.

1.4.6.1 Example: Nested header-defined section

# <section definition>
...
## <nested section definition>
...

1.4.6.2 Example: Nested list-defined section

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

2 II. Sections Reference

NOTE: Sections marked as “Abstract” serve as a base for other sections and as such they cannot be used directly.

2.1 1. Named section

Abstract

Parent sections: vary, see descendants

Nested sections: vary, see descendants

Markdown entity: header, list

Inherits from: none

2.1.0.1 Definition

Defined by a keyword followed by an optional section name - identifier in a Markdown header or list entity.

# <keyword> <identifier>

+ <keyword> <identifier>

2.1.0.2 Description

Named section is the base section for most of the API Blueprint sections. It conforms to the general section and as such it composes of a section name (identifier), description and nested sections or specific formatted content (see descendants descriptions).

2.3 3. Payload section

2.3.0.1 Definition

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.

2.3.0.2 Description

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 HTTP body.

Furthermore, in API Blueprint context, a payload include a description and a validation schema.

A payload section 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.

2.6 6. Schema section

2.6.0.1 Definition

2.6.0.2 Description

Specifies a validation schema for the HTTP message-body of parent payload section.

2.7 7. Metadata section

Parent sections: none

Nested sections: none

Markdown entity: special

Inherits from: none

2.7.0.1 Definition

Key value pairs. Key separated from its value by 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.

2.7.0.2 Description

Metadata keys and its values are tool-specific. Refer to relevant tool documentation for the list of supported keys.

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

2.11.0.2 Description

2.11.0.3 Referencing

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.

2.12 12. URI parameters section

2.12.0.1 Definition

Defined by the Parameters keyword written in a Markdown list item:

+ Parameters

2.12.0.2 Description

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. One list item per URI parameter. The nested list items subsections inherit from the Named section and are subject to additional formatting as follows:

2.13.0.2 Description

Definition of at least one complete HTTP transaction as performed with the parent resource section. An action section may consists 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.

Nested Request and Response sections may be ordered into groups where each groups represent one transaction example. 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.