+
API Blueprint Specification
+
+
+
+
+
Author: z@apiary.io
+Version: 1A9
+
+
+
+
+
+
+
+
+
+
+
+
Abstract
+
+
+
+
Section Basics
+
+
+
+
Going Further
+
+
+
+
+
+
+
+
+
+
+
+
+
+
I. API Blueprint Language
+
+
+
+
Introduction
+
+
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
+
+
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.
+
+
+
+
API Blueprint document
+
+
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.
+
+
Blueprint document structure
+
+
+
+
+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.
+
+
+
+
+
Blueprint section
+
+
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>
+=========
+
+...
+
+
+
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>
+
+...
+
+
+
+
+
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.
+
+
+
+
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.
+
+
+
# <keyword> <identifier>
+
+<description>
+
+<specific content>
+
+<nested sections>
+
+
Example: List-defined section structure
+
+ <keyword> <identifier>
+
+ <description>
+
+ <specific content>
+
+ <nested sections>
+
+
+
+
Keywords
+
+
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})
+
+
+
List keywords
+
+
+RequestResponseBodySchemaModel-
+
Header & Headers
+
+-
+
Parameter & Parameters
+
+Values-
+
Attribute & Attributes
+
+Relation
+
+
+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.
+
+
+
+
+
Identifier
+
+
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.
+
+
Example
+
+
+
+
+
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.
+
+
+
+
+
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.
+
+
+
# <section definition>
+
+ ...
+
+## <nested section definition>
+
+ ...
+
+
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.
+
+
+
+
+
+
+
II. Sections Reference
+
+
+NOTE: Sections marked as "Abstract" serve as a base for other sections
+and as such they cannot be used directly.
+
+
+
Abstract
+
+
+
+
Named section
+
+
+- Abstract
+-
+Parent sections: vary, see descendants
+-
+Nested sections: vary, see descendants
+-
+Markdown entity: header, list
+-
+Inherits from: none
+
+
+
Definition
+
+
Defined by a keyword followed by an optional section name -
+identifier in a Markdown header or list entity.
+
# <keyword> <identifier>
+
+
+ <keyword> <identifier>
+
+
Description
+
+
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).
+
+
Example
+
# <keyword> Section Name
+This the `Section Name` description.
+
+- one
+- **two**
+- three
+
+<nested sections> | <formatted content>
+
+
+
+
+
+
Asset section
+
+
+- Abstract
+-
+Parent sections: vary, see descendants
+-
+Nested sections: none
+-
+Markdown entity: list
+-
+Inherits from: none
+
+
+
Definition
+
+
Defined by a keyword in Markdown list entity.
+
+
Description
+
+
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.
+
+
Example
+
+ <keyword>
+
+ {
+ "message": "Hello"
+ }
+
+
Example: Fenced code blocks
+
+ <keyword>
+
+ ```
+ {
+ "message": "Hello"
+ }
+ ```
+
+
+
+
+
+
Payload section
+
+
+
+
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.
+
+
+
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 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.
+
+
Relation of Body, Schema and Attributes sections
+
+
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
+
+
+
+
+
Referencing
+
+
Instead of providing a payload section content, a
+model payload section can be referenced using the
+Markdown implicit reference syntax:
+
+
Example
+
+ <keyword> Payload Name (application/json)
+
+ This the `Payload Name` description.
+
+ + Headers
+
+ ...
+
+ + Body
+
+ ...
+
+ + Schema
+
+ ...
+
+
Example: Referencing model payload
+
+ <keyword> Payload Name
+
+ [Resource model identifier][]
+
+
+
+
Section Basics
+
+
+
+
+
+
+-
+Parent sections: none
+-
+Nested sections: none
+-
+Markdown entity: special
+-
+Inherits from: none
+
+
+
Definition
+
+
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.
+
+
Description
+
+
Metadata keys and their values are tool-specific. Refer to relevant tool
+documentation for the list of supported keys.
+
+
Example
+
FORMAT: 1A
+HOST: http://blog.acme.com
+
+
+
+
+
+
API name & overview section
+
+
+-
+Parent sections: none
+-
+Nested sections: none
+-
+Markdown entity: special, header
+-
+Inherits from: Named section
+
+
+
+
Definition
+
+
Defined by the first Markdown header in the blueprint document, unless it
+represents another section definition.
+
+
Description
+
+
Name and description of the API
+
+
Example
+
# Basic ACME Blog API
+Welcome to the **ACME Blog** API. This API provides access to the **ACME
+Blog** service.
+
+
+
+
+
+
Resource group section
+
+
+
+
Definition
+
+
Defined by the Group keyword followed by group name (identifier):
+
+
Description
+
+
This section represents a group of resources (Resource Sections). May
+include one or more nested Resource Sections.
+
+
Example
+
# Group Blog Posts
+
+## Resource 1 [/resource1]
+
+ ...
+
+# Group Authors
+Resources in this groups are related to **ACME Blog** authors.
+
+## Resource 2 [/resource2]
+
+ ...
+
+
+
+
+
+
Resource section
+
+
+
+
Definition
+
+
Defined by an 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.
+
+
+
Description
+
+
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:
+
+
+
+
+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).
+
+
+
Example
+
# Blog Posts [/posts/{id}]
+Resource representing **ACME Blog** posts.
+
+
+
+
+
+
+
+
Resource model section
+
+
+
+
Definition
+
+
Defined by the Model keyword followed by an optional media type:
+
+
Description
+
+
A resource manifestation - one
+exemplary representation of the resource in the form of a
+payload.
+
+
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.
+
+
Example
+
# My Resource [/resource]
+
++ Model (text/plain)
+
+ Hello World
+
+## Retrieve My Resource [GET]
+
++ Response 200
+
+ [My Resource][]
+
+
+
+
+
+
Schema section
+
+
+
+
Definition
+
+
Defined by the Schema keyword in Markdown list entity.
+
+
Description
+
+
Specifies a validation schema for the HTTP message-body of parent payload section.
+
+
Example
+
+
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"
+ }
+ }
+ }
+
+
+
+
+
+
Action section
+
+
+
+
Definition
+
+
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>]
+
+
Description
+
+
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.
+
+
Example
+
# 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
+
+
Example Multiple Transaction Examples
+
# 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, response 200
+
+- 2nd example: request
B, responses 200 and 500
+
+- 3rd example: requests
C and D, response 200
+
+
+
+
+
+
+
+
+
Request section
+
+
+
+
Definition
+
+
Defined by the Request keyword followed by an optional identifier:
+
+ Request <identifier> (<Media Type>)
+
+
Description
+
+
One HTTP request-message example – payload.
+
+
Example
+
+ Request Create Blog Post (application/json)
+
+ { "message" : "Hello World." }
+
+
+
+
+
+
Response section
+
+
+
+
Definition
+
+
Defined by the Response keyword. The response section definition should
+include an HTTP status code as its identifier.
+
+ Response <HTTP status code> (<Media Type>)
+
+
Description
+
+
One HTTP response-message example – payload.
+
+
Example
+
+ Response 201 (application/json)
+
+ { "message" : "created" }
+
+
+
+
+
+
URI parameters section
+
+
+
+
Definition
+
+
Defined by the Parameters keyword written in a Markdown list item:
+
+
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. 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.
+-
+
Members is the optional enumeration of possible values.
+<type> should be surrounded by enum[] if this is present.
+For example, if enumeration values are present for a parameter whose type is
+number, then enum[number] should be used instead of number to.
+-
+
<enumeration value n> represents an element of enumeration type.
+-
+
required is the optional specifier of a required parameter
+(this is the default)
+-
+
optional is 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.
+
+
+
Example
+
+
+ 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`
+
+
+
+
+
+
Attributes Section
+
+
+
+
Definition
+
+
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.
+
+
Example
+
+
Description
+
+
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).
+
+
Resource Attributes description
+
+
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.
+
+
Example
+
# 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 post
+
+
+NOTE: This data structure can be later referred as:
++ Attributes (Blog Post)
+
+
+
Action Attributes description
+
+
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.
+
+
Example
+
## 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 201
+
+
Payload Attributes description
+
+
Description 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.
+
+
Example
+
## 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
+
+
+
Definition
+
+
Defined by the Headers keyword in Markdown list entity.
+
+
Description
+
+
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.
+
+
Example
+
+ Headers
+
+ Accept-Charset: utf-8
+ Connection: keep-alive
+ Content-Type: multipart/form-data, boundary=AaB03x
+
+
+
+
+
+
Body section
+
+
+
+
Definition
+
+
Defined by the Body keyword in Markdown list entity.
+
+
Description
+
+
Specifies the HTTP message-body of a payload section.
+
+
Example
+
+ Body
+
+ {
+ "message": "Hello"
+ }
+
+
+
+
+
+
Data Structures section
+
+
+-
+Parent sections: none
+-
+Nested sections: MSON Named Type definition (see below)
+-
+Markdown entity: header
+-
+Inherits from: none
+
+
+
Definition
+
+
Defined by the Data Structures keyword.
+
+
Description
+
+
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.
+
+
Example
+
# Data Structures
+
+## Message (object)
+
++ text (string) - text of the message
++ author (Author) - author of the message
+
+## Author (object)
+
++ name: John
++ email: john@appleseed.com
+
+
Example reusing Data Structure in Resource
+
# User [/user]
+
++ Attributes (Author)
+
+# Data Structures
+
+## Author (object)
+
++ name: John
++ email: john@appleseed.com
+
+
Example reusing Resource-defined Data Structure
+
# User [/user]
+
++ Attributes
+ + name: John
+ + email: john@appleseed.com
+
+# Data Structures
+
+## Author (User)
+
+
+
+
+
+
Relation section
+
+
+-
+Parent sections: Action section
+
+-
+Nested Sections: none
+-
+Markdown entity: list
+-
+Inherits from: none
+
+
+
Definition
+
+
Defined by the Relation keyword written in a Markdown list item followed by a
+colon (:) and a link relation identifier.
+
+ Relation: <link relation identifier>
+
+
Description
+
+
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.
+
+
+
Example
+
# Task [/tasks/{id}]
+
++ Parameters
+ + id
+
+## Retrieve Task [GET]
+
++ Relation: task
++ Response 200
+
+ { ... }
+
+## Delete Task [DELETE]
+
++ Relation: delete
++ Response 204
+
+
+
+
+
+
+
+
III. Appendix
+
+
+
+
URI Templates
+
+
The API Blueprint uses a subset of RFC6570 to define a resource URI Template.
+
+
URI Path Segment
+
+
At its simplest form – without any variables – a path segment of an
+URI Template is identical to an URI path segment:
+
+
URI Template Variable
+
+
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.
+
+
Operators
+
+
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
+
+
+
Examples
+
{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.
+
+
+
Variable Reserved Values
+
+
Following characters are reserved in variable values:
+
+
: / / / ? / # / [ / ] / @ / ! / $ / & / ' / ( / ) / * / + / , / ; / =
+
+
Path Segment Variable
+
+
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
+
+
+
Fragment Identifier Variable
+
+
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
+
+
+
Variable with Reserved Characters Values
+
+
To define URI Template variables with reserved URI characters,
+use the plus (+) operator:
+
+
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
+
+
+
+
+
+