Repository: apiaryio/api-blueprint
Branch: master
Commit: 86fc3a128a93
Files: 28
Total size: 129.7 KB
Directory structure:
gitextract_jtccfgkk/
├── .gitignore
├── API Blueprint Specification.md
├── Advanced Tutorial.md
├── Glossary of Terms.md
├── LICENSE
├── README.md
├── Tutorial.md
└── examples/
├── 01. Simplest API.md
├── 02. Resource and Actions.md
├── 03. Named Resource and Actions.md
├── 04. Grouping Resources.md
├── 05. Responses.md
├── 06. Requests.md
├── 07. Parameters.md
├── 08. Attributes.md
├── 09. Advanced Attributes.md
├── 10. Data Structures.md
├── 11. Resource Model.md
├── 12. Advanced Action.md
├── 13. Named Endpoints.md
├── 14. JSON Schema.md
├── 15. Advanced JSON Schema.md
├── Gist Fox API + Auth.md
├── Gist Fox API.md
├── Polls API.md
├── Polls Hypermedia API.md
├── README.md
└── Real World API.md
================================================
FILE CONTENTS
================================================
================================================
FILE: .gitignore
================================================
_site
node_modules
.DS_Store
npm-debug.log
================================================
FILE: API Blueprint Specification.md
================================================
---
Author: z@apiary.io
Version: 1A9
---
# API Blueprint
#### Format 1A revision 9
## [I. API Blueprint Language](#def-api-blueprint-language)
+ [Introduction](#def-introduction)
+ [API Blueprint](#def-api-blueprint)
+ [API Blueprint document](#def-api-blueprint-document)
+ [Blueprint section](#def-blueprint-section)
+ [Section types](#def-section-types)
+ [Section structure](#def-section-structure)
+ [Keywords](#def-keywords)
+ [Identifier](#def-identifier)
+ [Description](#def-description)
+ [Nested sections](#def-nested-sections)
## [II. Sections Reference](#def-sections-reference)
### Abstract
+ [Named section](#def-named-section)
+ [Asset section](#def-asset-section)
+ [Payload section](#def-payload-section)
### Section Basics
+ [Metadata section](#def-metadata-section)
+ [API name & overview section](#def-api-name-section)
+ [Resource group section](#def-resourcegroup-section)
+ [Resource section](#def-resource-section)
+ [Resource model section](#def-model-section)
+ [Schema section](#def-schema-section)
+ [Action section](#def-action-section)
+ [Request section](#def-request-section)
+ [Response section](#def-response-section)
+ [URI parameters section](#def-uriparameters-section)
+ [Attributes section](#def-attributes-section)
+ [Headers section](#def-headers-section)
+ [Body section](#def-body-section)
### Going Further
+ [Data Structures section](#def-data-structures)
+ [Relation section](#def-relation-section)
## [III. Appendix](#def-appendix)
+ [URI Templates](#def-uri-templates)
---
<br>
<a name="def-api-blueprint-language"></a>
# I. API Blueprint Language
<a name="def-introduction"></a>
## 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](Tutorial.md) or check some of the [examples][].
<a name="def-api-blueprint"></a>
## 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][].
<a name="def-api-blueprint-document"></a>
## 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](#def-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
+ [`0-1` **Metadata** section](#def-metadata-section)
+ [`0-1` **API Name & overview** section](#def-api-name-section)
+ [`0+` **Resource** sections](#def-resource-section)
+ [`0-1` **URI Parameters** section](#def-uriparameters-section)
+ [`0-1` **Attributes** section](#def-attributes-section)
+ [`0-1` **Model** section](#def-model-section)
+ [`0-1` **Headers** section](#def-headers-section)
+ [`0-1` **Attributes** section](#def-attributes-section)
+ [`0-1` **Body** section](#def-body-section)
+ [`0-1` **Schema** section](#def-schema-section)
+ [`1+` **Action** sections](#def-action-section)
+ [`0-1` **Relation** section](#def-relation-section)
+ [`0-1` **URI Parameters** section](#def-uriparameters-section)
+ [`0-1` **Attributes** section](#def-attributes-section)
+ [`0+` **Request** sections](#def-request-section)
+ [`0-1` **Headers** section](#def-headers-section)
+ [`0-1` **Attributes** section](#def-attributes-section)
+ [`0-1` **Body** section](#def-body-section)
+ [`0-1` **Schema** section](#def-schema-section)
+ [`1+` **Response** sections](#def-response-section)
+ [`0-1` **Headers** section](#def-headers-section)
+ [`0-1` **Attributes** section](#def-attributes-section)
+ [`0-1` **Body** section](#def-body-section)
+ [`0-1` **Schema** section](#def-schema-section)
+ [`0+` **Resource Group** sections](#def-resourcegroup-section)
+ [`0+` **Resource** sections](#def-resource-section) (see above)
+ [`0+` **Data Structures** section](#def-data-structures)
> **NOTE:** The number prior to a section name denotes the allowed number of
> the section occurrences.
> **NOTE:** Refer to [Sections Reference](#def-sections-reference) for
> description of a specific section type.
<a name="def-blueprint-section"></a>
## 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](#def-metadata-section) and
> the [API Name & Overview section](#def-api-name-section). Refer to the respective section entry
> for details on its definition.
#### 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>
> =========
>
> ...
#### 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>
>
> ...
<a name="def-section-types"></a>
### Section types
There are several types of API Blueprint sections. You can find the complete
listing of the section types in the
[Section Reference](#def-sections-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 name="def-section-structure"></a>
### 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.
#### Example: Header-defined section structure
# <keyword> <identifier>
<description>
<specific content>
<nested sections>
#### Example: List-defined section structure
+ <keyword> <identifier>
<description>
<specific content>
<nested sections>
<a name="def-keywords"></a>
### Keywords
Following reserved keywords are used in section definitions:
#### Header keywords
- `Group`
- `Data Structures`
- [HTTP methods][httpmethods] (e.g. `GET, POST, PUT, DELETE`...)
- [URI templates][uritemplate] (e.g. `/resource/{id}`)
- Combinations of an HTTP method and URI Template (e.g. `GET /resource/{id}`)
#### List keywords
- `Request`
- `Response`
- `Body`
- `Schema`
- `Model`
- `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.
<a name="def-identifier"></a>
### 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](#def-keywords).
#### Example
```
Adam's Message 42
```
```
my-awesome-message_2
```
<a name="def-description"></a>
### 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](#def-keywords).
> **NOTE:** It is considered good practice to keep the header level nested
> under the actual section.
<a name="def-nested-sections"></a>
### 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.
Which sections can be nested and where depends upon the section in case, as
described in the relevant section's entry.
#### Example: Nested header-defined section
# <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.
---
<a name="def-sections-reference"></a>
# II. Sections Reference
> **NOTE:** Sections marked as "Abstract" serve as a base for other sections
> and as such they **cannot** be used directly.
# Abstract
<a name="def-named-section"></a>
## 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](#def-keywords) followed by an optional section name -
[identifier](#def-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](#def-section-structure) 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>
---
<a name="def-asset-section"></a>
## Asset section
- **Abstract**
- **Parent sections:** vary, see descendants
- **Nested sections:** none
- **Markdown entity:** list
- **Inherits from**: none
#### Definition
Defined by a [keyword](#def-keywords) in Markdown list entity.
+ <keyword>
#### 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](http://daringfireball.net/projects/markdown/syntax#precode).
#### Example
+ <keyword>
{
"message": "Hello"
}
#### Example: Fenced code blocks
+ <keyword>
```
{
"message": "Hello"
}
```
---
<a name="def-payload-section"></a>
## Payload section
- **Abstract**
- **Parent sections:** vary, see descendants
- **Nested sections:** [`0-1` Headers section](#def-headers-section), [`0-1` Attributes section](#def-attributes-section), [`0-1` Body section](#def-body-section), [`0-1` Schema section](#def-schema-section)
- **Markdown entity:** list
- **Inherits from**: [Named section](#def-named-section)
#### Definition
Defined by a [keyword](#def-keywords) 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](#def-body-section).
This section **should** include at least one of the following nested sections:
- [`0-1` Headers section](#def-headers-section)
- [`0-1` Attributes section](#def-attributes-section)
- [`0-1` Body section](#def-body-section)
- [`0-1` Schema section](#def-schema-section)
If there is no nested section the content of the payload section is considered
as content of the [Body section](#def-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:
1. For resolving message-body schema
1. Schema section
2. Attributes section
3. Body section
2. For resolving message-body example
1. Body section
2. Attributes section
3. Schema section
#### Referencing
Instead of providing a payload section content, a
[model payload section](#def-model-section) can be referenced using the
Markdown implicit [reference syntax][]:
[<identifier>][]
#### 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
<a name="def-metadata-section"></a>
## Metadata section
- **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
---
<a name="def-api-name-section"></a>
## API name & overview section
- **Parent sections:** none
- **Nested sections:** none
- **Markdown entity:** special, header
- **Inherits from**: [Named section](#def-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.
---
<a name="def-resourcegroup-section"></a>
## Resource group section
- **Parent sections:** none
- **Nested sections:** [`0+` Resource section](#def-resource-section)
- **Markdown entity:** header
- **Inherits from**: [Named section](#def-named-section)
#### Definition
Defined by the `Group` keyword followed by group [name (identifier)](#def-identifier):
# Group <identifier>
#### Description
This section represents a group of resources (Resource Sections). **May**
include one or more nested [Resource Sections](#def-resource-section).
#### Example
```apib
# Group Blog Posts
## Resource 1 [/resource1]
...
# Group Authors
Resources in this groups are related to **ACME Blog** authors.
## Resource 2 [/resource2]
...
```
---
<a name="def-resource-section"></a>
## Resource section
- **Parent sections:** none, [Resource group section](#def-resourcegroup-section)
- **Nested sections:** [`0-1` Parameters section](#def-uriparameters-section), [`0-1` Attributes section](#def-attributes-section), [`0-1` Model section](#def-model-section), [`1+` Action section](#def-action-section)
- **Markdown entity:** header
- **Inherits from**: [Named section](#def-named-section)
#### Definition
Defined by an [URI template][uritemplate]:
# <URI template>
**-- or --**
Defined by a resource [name (identifier)](#def-identifier) followed by an
[URI template][uritemplate] enclosed in square brackets `[]`.
# <identifier> [<URI template>]
**-- or --**
Defined by an [HTTP request method][httpmethods] followed by [URI template][uritemplate]:
# <HTTP request method> <URI template>
**-- or --**
Defined by a resource [name (identifier)](#def-identifier) followed by an
[HTTP request method][httpmethods] and an [URI template][uritemplate] 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](#def-action-section) including its description and nested
> sections and **follows the rules of the Action section instead**.
#### Description
An API [resource](http://www.w3.org/TR/di-gloss/#def-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](#def-action-section) and **may** include following nested
sections:
- [`0-1` URI parameters section](#def-uriparameters-section)
URI parameters defined in the scope of a Resource section apply to
_any and all_ nested Action sections except when an [URI template][uritemplate] has
been defined for the Action.
- [`0-1` Attributes section][]
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][].
- [`0-1` Model section](#def-model-section)
- Additional [Action sections](#def-action-section)
> **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
```apib
# Blog Posts [/posts/{id}]
Resource representing **ACME Blog** posts.
```
```apib
# /posts/{id}
```
```apib
# GET /posts/{id}
```
---
<a name="def-model-section"></a>
## Resource model section
- **Parent sections:** [Resource section](#def-resource-section)
- **Nested sections:** [Refer to payload section](#def-payload-section)
- **Markdown entity:** list
- **Inherits from**: [Payload section](#def-payload-section)
#### Definition
Defined by the `Model` keyword followed by an optional media type:
+ Model (<media type>)
#### Description
A [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) - one
exemplary representation of the resource in the form of a
[payload](#def-payload-section).
#### 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](#def-request-section)
or [Response](#def-response-section) payload sections using the Markdown
implicit [reference syntax][].
#### Example
```apib
# My Resource [/resource]
+ Model (text/plain)
Hello World
## Retrieve My Resource [GET]
+ Response 200
[My Resource][]
```
---
<a name="def-schema-section"></a>
## Schema section
- **Parent sections:** [Payload section](#def-payload-section)
- **Nested sections:** none
- **Markdown entity:** list
- **Inherits from**: [Asset section](#def-asset-section)
#### Definition
Defined by the `Schema` keyword in Markdown list entity.
+ Schema
#### Description
Specifies a validation schema for the HTTP message-body of parent payload section.
#### Example
Following example uses [Body section](#def-body-section) to provide an example of an `application/json` payload, and [Schema section](#def-schema-section) to provide a [JSON Schema](http://json-schema.org/) describing all possible valid shapes of the payload.
```apib
## 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"
}
}
}
```
---
<a name="def-action-section"></a>
## Action section
- **Parent sections:** [Resource section](#def-resource-section)
- **Nested sections:**
[`0-1` Relation section](#def-relation-section),
[`0-1` URI parameters section](#def-uriparameters-section),
[`0-1` Attributes section](#def-attributes-section),
[`0+` Request section](#def-request-section),
[`1+` Response section](#def-response-section)
- **Markdown entity:** header
- **Inherits from**: [Named section](#def-named-section)
#### Definition
Defined by an [HTTP request method][httpmethods]:
## <HTTP request method>
**-- or --**
Defined by an action [name (identifier)](#def-identifier) followed by an
[HTTP request method][httpmethods] enclosed in square brackets `[]`.
## <identifier> [<HTTP request method>]
**-- or --**
Defined by an action [name (identifier)](#def-identifier) followed by an
[HTTP request method][httpmethods] and
[URI template][uritemplate] 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](#def-uriparameters-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](#def-response-section) and **may** include additional nested
[Request](#def-request-section) and [Response](#def-response-section) 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
```apib
# 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
```apib
# 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:
>
> 1. 1st example: request `A`, response `200`
> 2. 2nd example: request `B`, responses `200` and `500`
> 3. 3rd example: requests `C` and `D`, response `200`
---
<a name="def-request-section"></a>
## Request section
- **Parent sections:** [Action section](#def-action-section)
- **Nested sections:** [Refer to payload section](#def-payload-section)
- **Markdown entity:** list
- **Inherits from**: [Payload section](#def-payload-section)
#### Definition
Defined by the `Request` keyword followed by an optional [identifier](#def-identifier):
+ Request <identifier> (<Media Type>)
#### Description
One HTTP request-message example – payload.
#### Example
```apib
+ Request Create Blog Post (application/json)
{ "message" : "Hello World." }
```
---
<a name="def-response-section"></a>
## Response section
- **Parent sections:** [Action section](#def-action-section)
- **Nested sections:** [Refer to payload section](#def-payload-section)
- **Markdown entity:** list
- **Inherits from**: [Payload section](#def-payload-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
```apib
+ Response 201 (application/json)
{ "message" : "created" }
```
---
<a name="def-uriparameters-section"></a>
## URI parameters section
- **Parent Sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section)
- **Nested Sections:** none
- **Markdown entity:** list
- **Inherits from**: none, special
#### Definition
Defined by the `Parameters` keyword written in a Markdown list item:
+ Parameters
#### 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](#def-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](#def-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](#def-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
```apib
# GET /posts/{id}
```
```apib
+ Parameters
+ id - Id of a post.
```
```apib
+ Parameters
+ id (number) - Id of a post.
```
```apib
+ Parameters
+ id: `1001` (number, required) - Id of a post.
```
```apib
+ Parameters
+ id: `1001` (number, optional) - Id of a post.
+ Default: `20`
```
```apib
+ Parameters
+ id (enum[string])
Id of a Post
+ Members
+ `A`
+ `B`
+ `C`
```
---
<a name="def-attributes-section"></a>
## Attributes Section
- **Parent sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section) | [Payload section](#def-payload-section)
- **Nested sections:** See **[Markdown Syntax for Object Notation][MSON]**
- **Markdown entity:** list
- **Inherits from**: none
#### 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
```apib
+ Attributes (object)
```
#### Description
This section describes a data structure using the
**[Markdown Syntax for Object Notation][MSON] (MSON)**.
Based on the parent section, the data structure being described is one of the
following:
1. Resource data structure attributes ([Resource section](#def-resource-section))
2. Action request attributes ([Action section](#def-action-section))
3. Payload message-body attributes ([Payload section](#def-payload-section))
Data structures defined in this section **may** refer to any arbitrary data
structures defined in the [Data Structures section](#def-data-structures) 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](#def-resource-section), this data
structure **may** be referenced by other data structures using the resource
name.
##### Example
```apib
# 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](#def-request-section) of the respective
[Action section](#def-action-section) inherits these attributes unless
specified otherwise.
##### Example
```apib
## 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](#def-body-section) example, if a Body section is provided.
If defined, the [Body section](#def-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](#def-schema-section) is
provided. When a Schema section is provided, the attributes description
**should** conform to the schema.
##### Example
```apib
## Retrieve a Post [GET]
+ Response 200 (application/json)
+ Attributes (object)
+ message (string) - Message to the world
+ Body
{ "message" : "Hello World." }
```
---
<a name="def-headers-section"></a>
## Headers section
- **Parent sections:** [Payload section](#def-payload-section)
- **Nested sections:** none
- **Markdown entity:** list
- **Inherits from**: none
#### Definition
Defined by the `Headers` keyword in Markdown list entity.
+ Headers
#### Description
Specifies the HTTP message-headers of the parent payload section. The content
this section is expected to be a [pre-formatted code block](http://daringfireball.net/projects/markdown/syntax#precode)
with the following syntax:
<HTTP header name>: <value>
One HTTP header per line.
#### Example
```apib
+ Headers
Accept-Charset: utf-8
Connection: keep-alive
Content-Type: multipart/form-data, boundary=AaB03x
```
---
<a name="def-body-section"></a>
## Body section
- **Parent sections:** [Payload section](#def-payload-section)
- **Nested sections:** none
- **Markdown entity:** list
- **Inherits from**: [Asset section](#def-asset-section)
#### Definition
Defined by the `Body` keyword in Markdown list entity.
+ Body
#### Description
Specifies the HTTP message-body of a payload section.
#### Example
```apib
+ Body
{
"message": "Hello"
}
```
---
<a name="def-data-structures"></a>
## 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.
# Data Structures
#### 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
```apib
# 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
```apib
# User [/user]
+ Attributes (Author)
# Data Structures
## Author (object)
+ name: John
+ email: john@appleseed.com
```
#### Example reusing Resource-defined Data Structure
```apib
# User [/user]
+ Attributes
+ name: John
+ email: john@appleseed.com
# Data Structures
## Author (User)
```
---
<a name="def-relation-section"></a>
## Relation section
- **Parent sections:** [Action section](#def-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](https://tools.ietf.org/html/rfc5988#section-4)
for the given action as specified by [RFC 5988](https://tools.ietf.org/html/rfc5988).
> **NOTE:** The link relation identifiers should be unique per resource in the blueprint document.
#### Example
```apib
# Task [/tasks/{id}]
+ Parameters
+ id
## Retrieve Task [GET]
+ Relation: task
+ Response 200
{ ... }
## Delete Task [DELETE]
+ Relation: delete
+ Response 204
```
---
<br>
<a name="def-appendix"></a>
# III. Appendix
<a name="def-uri-templates"></a>
## URI Templates
The API Blueprint uses a subset of [RFC6570][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:
```
/path/to/resources/42
```
### 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][pct-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][uri-explode] 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:
```
/path/{+var}/42
```
With `var := to/resources` the expansion is `/path/to/resources/42`.
> **NOTE:** RFC6570 – Level 2
### Form-style Query Variable
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
---
[apiblueprint.org]: http://apiblueprint.org
[markdown syntax]: http://daringfireball.net/projects/markdown
[reference syntax]: http://daringfireball.net/projects/markdown/syntax#link
[gitHub flavored markdown syntax]: https://help.github.com/articles/github-flavored-markdown
[httpmethods]: https://github.com/for-GET/know-your-http-well/blob/master/methods.md#know-your-http-methods-well
[uritemplate]: #def-uri-templates
[rfc6570]: http://tools.ietf.org/html/rfc6570
[HTTP status code]: https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md
[header syntax]: https://daringfireball.net/projects/markdown/syntax#header
[list syntax]: https://daringfireball.net/projects/markdown/syntax#list
[pct-encoded]: http://en.wikipedia.org/wiki/Percent-encoding
[uri-explode]: http://tools.ietf.org/html/rfc6570#section-2.4.2
[examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples
[MSON]: https://github.com/apiaryio/mson
[MSON Named Types]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#22-named-types
[MSON Type Definition]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#35-type-definition
[`0-1` Attributes section]: #def-attributes-section
[Attributes section]: #def-attributes-section
[Attributes sections]: #def-attributes-section
[Resource Section]: #def-resource-section
[Request section]: #def-request-section
================================================
FILE: Advanced Tutorial.md
================================================
# Advanced API Blueprint Tutorial
Welcome to the advanced API Blueprint tutorial! This tutorial will take you
through advanced topics like JSON Schema, request and response attributes, data
structures and relation types.
This tutorial assumes that you have read the [API Blueprint Tutorial](https://github.com/apiaryio/api-blueprint/blob/master/Tutorial.md).
## JSON Schema
Action request and response bodies can have associated schemas that describe
the allowed structure of the body content. JSON bodies are typically described
with [JSON Schema](http://json-schema.org/). Given a simple JSON response body
we can describe the structure of the response with JSON Schema in a `+ Schema`
section.
The schema can describe the type of each member, which members are required,
default values, and support a number of other advanced features. Below is an
example, taken from the
[Polls API](https://raw.github.com/apiaryio/api-blueprint/master/examples/Polls%20API.md)
blueprint:
```apib
### 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.
+ Request (application/json)
+ Body
{
"question": "Favourite language?"
"choices": [
"Swift",
"Objective-C"
]
}
+ Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"question": {
"type": "string"
},
"choices": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2
}
}
}
```
## Attributes
Another way of describing examples and the structure of your request and
response content is by using [MSON](https://github.com/apiaryio/mson#readme).
MSON, like API Blueprint, allows you to use human-readable plain text to
describe things rather than formats designed for computer parsing like JSON or
YAML. Where API Blueprint allows you to describe your API, MSON allows you to
describe data structures.
MSON can be added to resources, actions, and individual requests or responses
via an `+ Attributes` section.
Creating a new question in the polls API can be modeled using MSON:
```apib
### 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.
+ Request (application/json)
+ Attributes
+ question: Favourite Language? (required)
+ choices: Swift, `Objective-C` (array, required)
```
When the above blueprint is parsed it will have a JSON body and JSON Schema
example generated for it from the MSON attributes. Note, however, that the
generated JSON Schema may differ from a hand-written one. In this example, the
`minItems` will not be set. If you have such constraints you can override the
generated schema by providing your own, in which case only the JSON body will
be generated.
## Data Structures
Once you start using MSON, you may find yourself wanting to reuse certain
commonly used or nested data structure components. This is possible with the
`## Data Structures` section. Attributes sections can then reference the data
structures defined in the Data Structures or other resource sections by name.
For example, using the polls API question collection resource, we can split out
the `Question` and `Choice` objects:
```apib
### List All Questions [GET]
+ Response 200 (application/json)
+ Attributes (array[Question])
## Data Structures
### Question
+ question: Favourite programming language? (required)
+ published_at: `2014-11-11T08:40:51.620Z` (required)
+ url: /questions/1 (required)
+ choices (array[Choice], required)
### Choice
+ choice: Javascript (required)
+ url: /questions/1/choices/1 (required)
+ votes: 2048 (number, required)
```
## Relation Types
Actions in a blueprint can define a semantic domain-specific meaning by
defining a relation type using a `+ Relation` section. This means that an
action can have a specific meaning regardless of its URI or name, and allows
clients to be built based on the domain of the API rather than specific URIs.
For example, in the polls API:
```apib
## Question [/question/{id}]
### View a Question Detail [GET]
+ Relation: self
### Delete a Question [DELETE]
+ Relation: delete
## Questions Collection [/questions]
### List All Questions [GET]
+ Relation: self
```
A server or client implementation can now use this information to handle the
specific API resource and action URIs. Please see the
[Web Linking RFC 5988](https://tools.ietf.org/html/rfc5988) and the
[IANA Link Relation Types](http://www.iana.org/assignments/link-relations/link-relations.xhtml) for
more information.
## Conclusion
This tutorial has covered some advanced API Blueprint topics.
For more in-depth information and other advanced topics,
please see the [API Blueprint Specification](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md).
================================================
FILE: Glossary of Terms.md
================================================
# API Blueprint Glossary of Terms
A brief list of terms as used in the [API Blueprint](http://apiblueprint.org) context.
## Glossary
<a name="def-action"></a>
### Action
An **HTTP transaction** (a request-response transaction).
Actions are specified by an [HTTP request method](#def-method) within a [resource](#def-resource).
<a name="def-api"></a>
### API
An **HTTP Application programming interface**. Might refer to an API
description. See [**API Blueprint**](#def-api-blueprint).
<a name="def-api-blueprint"></a>
### API Blueprint
The **API Blueprint language**. A format used to describe API in an API blueprint file.
<a name="def-asset"></a>
### Asset
**Atomic data**. Most often representing one resource representation in the form of message-body or its validation schema.
<a name="def-attribute"></a>
### Attribute
Based on the context, attribute (property) of a message-body data structure, or
attribute of a resource, or an input attribute of a transition –
[Action](#def-action).
<a name="def-blueprint"></a>
### Blueprint
An **API description**. A **blueprint file** (or a set of files) that describes an API using the API Blueprint language.
<a name="def-data-structure"></a>
### Data Structure
A particular data organization, or a description of it. In API Blueprint, data
structures and their [Attributes](#def-attribute) are described using the
Markdown Syntax for Object Notation – [MSON][].
<a name="def-entity"></a>
### Entity
[**Entity**](http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html) being transferred in a [payload](#def-payload).
<a name="def-header"></a>
### Header
A [**message-header**](#def-message-header).
<a name="def-method"></a>
### Method
An [**HTTP Request Method**](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods).
<a name="def-message"></a>
### Message
An **HTTP transaction message**.
<a name="def-message-body"></a>
### Message body
An [**asset**](#def-asset) representing [**HTTP transaction message body**](http://en.wikipedia.org/wiki/HTTP_body_data).
<a name="def-message-header"></a>
### Message header
An [**asset**](#def-asset) representing [**HTTP transaction message header**](http://en.wikipedia.org/wiki/List_of_HTTP_header_fields).
<a name="def-parameter"></a>
### Parameter
An [**URI template**](#def-uri-template) **variable**.
<a name="def-payload"></a>
### Payload
An **HTTP transaction message** including its **discussion** and any additional [**assets**](#def-asset) such as entity-body validation schema.
A payload may have an **identifier** – a string for a [request](#def-request)
payload or an
[HTTP status code](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for a
[response](#def-response) payload.
<a name="def-property"></a>
### Property
An [entity](#def-entity) field (attribute).
<a name="def-request"></a>
### Request
A [**payload**](#def-payload) containing one specific [HTTP Request](http://www.w3.org/TR/di-gloss/#def-http-request).
<a name="def-response"></a>
### Response
A [**payload**](#def-payload) containing one specific [HTTP Response](http://www.w3.org/TR/di-gloss/#def-http-response).
<a name="def-resource"></a>
### Resource
An API [**resource**](http://www.w3.org/TR/di-gloss/#def-resource) specified by
its *URI*. It can also refer to a [**set of resources**](#def-resource)
matching one [**URI template**](#def-uri-template).
<a name="def-resource-model"></a>
### Resource Model
One [**manifestation of a resource**](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) in the
form of a [payload](#def-payload). A resource model is an example
representation of its resource. Can be referenced later in the place of a
[payload](#def-payload).
<a name="def-resource-set"></a>
### Resource Set
A set of API [**resources**](http://www.w3.org/TR/di-gloss/#def-resource). Its
*URI* matches one specific [**URI template**](#def-uri-template).
<a name="def-trait"></a>
### Trait
A quality or characteristic of an API Blueprint SECTION.
<a name="def-schema"></a>
### Schema
A **validation schema** in a form of an [**asset**](#def-asset) used to validate (or describe) a [**message-body**](#def-message-body).
<a name="def-uri-template"></a>
### URI template
A compact sequence of characters for describing a range of **Uniform Resource Identifiers** through **variable** expansion, see [**RFC 6570**](http://tools.ietf.org/html/rfc6570).
## Additional resources
+ [HTTP/1.1 Terminology](http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html#sec1.3)
+ [W3C Glossary of Terms for Device Independence](http://www.w3.org/TR/di-gloss)
+ [Know your HTTP well](https://github.com/for-GET/know-your-http-well)
+ [Markdown Syntax for Object Notation][MSON]
[MSON]: https://github.com/apiaryio/mson
================================================
FILE: LICENSE
================================================
(The MIT License)
Copyright (c) 2014 Apiary Inc. <support@apiary.io>.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
================================================
FILE: README.md
================================================
# API Blueprint
### API Design for Humans
A powerful high-level API design language for web APIs.
API Blueprint is simple and accessible to everybody involved in the API design
lifecycle. Its syntax is concise yet expressive.
With API Blueprint you can quickly prototype and model APIs to be created or
describe already deployed mission-critical APIs. From a [car][tesla] to the
largest Content Distribution Network (CDN) in the world.
The API Blueprint is built to encourage dialogue and collaboration between
project stakeholders, developers and customers at any point in the API
lifecycle. At the same time, the API Blueprint [tools][] provide the support to
achieve the goals be it API development, governance or delivery.
[tesla]: https://github.com/timdorr/model-s-api/blob/master/apiary.apib
[tools]: http://apiblueprint.org/tools.html
## Open Source
API Blueprint is completely open sourced under the MIT license.
Any [contribution][contribute] is highly appreciated.
[contribute]: #contribute
## At home on GitHub
API Blueprint language is recognized by GitHub. You can
[search for API Blueprint][search] or use the `apib` language identifier for
[syntax highlighting][gfm].
[search]: https://github.com/search?utf8=%E2%9C%93&q=language%3A%22API+Blueprint%22&type=Repositories&ref=advsearch&l=API+Blueprint&l=
[gfm]: https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting
## Getting started
All it takes to describe an endpoint of your API is to write:
```apib
# GET /message
+ Response 200 (text/plain)
Hello World!
```
in your favorite plain text editor.
With this blueprint you can already get a [mock][], [documentation][] and
[test][] for your API before you even start coding.
To learn more about the API Blueprint syntax jump directly to the
[API Blueprint Tutorial][tutorial] or take a look at some [examples][].
[mock]: http://docs.apibstart.apiary.io/#reference/0/message/get?console=1
[documentation]: https://apiblueprint.org/documentation/
[test]: http://dredd.readthedocs.org/en/latest/
[tutorial]: Tutorial.md
[examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples
## Media Type
The media type for API Blueprint is `text/vnd.apiblueprint`.
## Learn more
- [Tutorial][tutorial]
- [Advanced Tutorial][advanced_tutorial]
- [Examples][examples]
- [Wiki][wiki]
- [Glossary of Terms][glossary]
- [Specification][specification]
- [List of Tools][tools]
- [Developers][developers]
[advanced_tutorial]: Advanced%20Tutorial.md
[glossary]: Glossary%20of%20Terms.md
[specification]: API%20Blueprint%20Specification.md
[wiki]: https://github.com/apiaryio/api-blueprint/wiki
[developers]: https://apiblueprint.org/developers.html
## Future
The plans for API Blueprint are completely tracked on GitHub – see the
[API Blueprint Roadmap][roadmap].
[roadmap]: https://github.com/apiaryio/api-blueprint/wiki/Roadmap
## Developers
Building tools for API Blueprint is possible thanks to its machine-friendly face
provided by API Blueprint parser.
If you are interested in building tools for API Blueprint check out the
[Developing tools for API Blueprint][developers].
## Contribute
Feel free report problems or propose new ideas using the API Blueprint GitHub
[issues][].
We use an RFC process for proposing any substantial changes to the API
Blueprint language, specification and/or parsers.
If you would like to propose a change, please consult our
[RFC process][rfc].
[issues]: https://github.com/apiaryio/api-blueprint/issues
[rfc]: https://github.com/apiaryio/api-blueprint-rfcs
## Get in Touch
- [@apiblueprint](https://twitter.com/apiblueprint)
- [Slack](https://apiblueprint-slack.herokuapp.com/)
- [Stack Overflow](http://stackoverflow.com/questions/tagged/apiblueprint)
- [GitHub Issues][issues]
## License
MIT License. See the [LICENSE](https://github.com/apiaryio/api-blueprint/blob/master/LICENSE)
file.
================================================
FILE: Tutorial.md
================================================
# 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][Poll API Blueprint] of the blueprint used in this tutorial for
reference.
> **Note:** **Additional API Blueprint Resources**
>
> + [Language Specification][specification]
> + [Examples][API Blueprint Examples]
> + [Glossary of Terms][API Blueprint Glossary of Terms]
> + [API Blueprint Map][map]
> + [Tools for API Blueprint][Tooling Section]
## API Blueprint
The first step for creating a blueprint is to specify the API Name and
metadata. This step looks as follows:
```apib
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.
```apib
# Group Questions
Resources 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.
```apib
## 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.
```apib
### 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 response 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.
```apib
+ 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.
```apib
### 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:
```apib
+ 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.
```apib
+ 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.
```apib
## 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}`.
<a id="uri-parameters"></a>
### URI Parameters
URI parameters should describe the URI using a list of Parameters. For
“Question” it would be as follows:
```apib
+ Parameters
+ question_id (number) - ID of the Question in the 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 question's detail.
```apib
### 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.
```apib
### Delete [DELETE]
+ Response 204
```
## Complete Blueprint
You can find an [implementation](http://github.com/apiaryio/polls-api) 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.
[GitHub Gists]: https://gist.github.com
[API Blueprint Glossary of Terms]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md
[API Blueprint Identifier]: https://github.com/apiaryio/api-blueprint/blob/1A/API%20Blueprint%20Specification.md#Identifiers
[HTTP Request Method]: https://github.com/for-GET/know-your-http-well/blob/master/methods.md
[status code]: https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md
[message-headers]: https://github.com/for-GET/know-your-http-well/blob/master/headers.md
[payload]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#payload
[URI Template]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#uri-template
[URI Parameters Section]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-uriparameters-section
[Markdown pre-formatted code blocks]: http://daringfireball.net/projects/markdown/syntax#precode
[URI Parameters]: #uri-parameters
[API Blueprint Examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples
[Poll API Blueprint]: https://raw.github.com/apiaryio/api-blueprint/master/examples/Polls%20API.md
[rendered on Apiary]: http://docs.pollsapi.apiary.io
[Tooling Section]: http://apiblueprint.org/tools.html
[apiblueprint.org]: http://apiblueprint.org
[specification]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md
[map]: https://github.com/apiaryio/api-blueprint/wiki/API-Blueprint-Map
================================================
FILE: examples/01. Simplest API.md
================================================
FORMAT: 1A
# The Simplest API
This is one of the simplest APIs written in the **API Blueprint**. One plain
resource combined with a method and that's it! We will explain what is going on
in the next installment -
[Resource and Actions](02.%20Resource%20and%20Actions.md).
**Note:** As we progress through the examples, do not also forget to view the
[Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md)
code to see what is really going on in the API Blueprint, as opposed to just
seeing the output of the Github Markdown parser.
Also please keep in mind that every single example in this course is a **real
API Blueprint** and as such you can **parse** it with the
[API Blueprint parser](https://github.com/apiaryio/drafter) or one of its
[bindings](https://github.com/apiaryio/drafter#bindings).
## API Blueprint
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md)
+ [Next: Resource and Actions](02.%20Resource%20and%20Actions.md)
# GET /message
+ Response 200 (text/plain)
Hello World!
================================================
FILE: examples/02. Resource and Actions.md
================================================
FORMAT: 1A
# Resource and Actions API
This API example demonstrates how to define a resource with multiple actions.
## API Blueprint
+ [Previous: The Simplest API](01.%20Simplest%20API.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/02.%20Resource%20and%20Actions.md)
+ [Next: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md)
# /message
This is our [resource](http://www.w3.org/TR/di-gloss/#def-resource). It is
defined by its
[URI](http://www.w3.org/TR/di-gloss/#def-uniform-resource-identifier) or, more
precisely, by its [URI Template](http://tools.ietf.org/html/rfc6570).
This resource has no actions specified but we will fix that soon.
## GET
Here we define an action using the `GET` [HTTP request method](http://www.w3schools.com/tags/ref_httpmethods.asp) for our resource `/message`.
As with every good action it should return a
[response](http://www.w3.org/TR/di-gloss/#def-http-response). A response always
bears a status code. Code 200 is great as it means all is green. Responding
with some data can be a great idea as well so let's add a plain text message to
our response.
+ Response 200 (text/plain)
Hello World!
## PUT
OK, let's add another action. This time to put new data to our resource
(essentially an update action). We will need to send something in a
[request](http://www.w3.org/TR/di-gloss/#def-http-request) and then send a
response back confirming the posting was a success (_HTTP Status Code 204 ~
Resource updated successfully, no content is returned_).
+ Request (text/plain)
All your base are belong to us.
+ Response 204
================================================
FILE: examples/03. Named Resource and Actions.md
================================================
FORMAT: 1A
# Named Resource and Actions API
This API example demonstrates how to name a resource and its actions, to give
the reader a better idea about what the resource is used for.
## API Blueprint
+ [Previous: Resource and Actions](02.%20Resource%20and%20Actions.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/03.%20Named%20Resource%20and%20Actions.md)
+ [Next: Grouping Resources](04.%20Grouping%20Resources.md)
# My Message [/message]
OK, `My Message` probably isn't the best name for our resource but it will do
for now. Note the URI `/message` is enclosed in square brackets.
## Retrieve a Message [GET]
Now this is informative! No extra explanation needed here. This action clearly
retrieves the message.
+ Response 200 (text/plain)
Hello World!
## Update a Message [PUT]
`Update a message` - nice and simple naming is the best way to go.
+ Request (text/plain)
All your base are belong to us.
+ Response 204
================================================
FILE: examples/04. Grouping Resources.md
================================================
FORMAT: 1A
# Grouping Resources API
This API example demonstrates how to group resources and form **groups of
resources**. You can create as many or as few groups as you like. If you do not
create any group all your resources will be part of an "unnamed" group.
## API Blueprint
+ [Previous: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/04.%20Grouping%20Resources.md)
+ [Next: Responses](05.%20Responses.md)
# Group Messages
Group of all messages-related resources.
This is the first group of resources in this document. It is **recognized** by
the **keyword `group`** and its name is `Messages`.
Any following resource definition is considered to be a part of this group
until another group is defined. It is **customary** to increase header level of
resources (and actions) nested under a resource.
## My Message [/message]
### Retrieve a Message [GET]
+ Response 200 (text/plain)
Hello World!
### Update a Message [PUT]
+ Request (text/plain)
All your base are belong to us.
+ Response 204
# Group Users
Group of all user-related resources.
This is the second group in this blueprint. For now, no resources were defined
here and as such we will omit it from the next installment of this course.
================================================
FILE: examples/05. Responses.md
================================================
FORMAT: 1A
# Responses API
In this API example we will discuss what information a response can bear and
how to define multiple responses. Technically a response is represented by a
payload that is sent back in response to a request.
## API Blueprint
+ [Previous: Grouping Resources](04.%20Grouping%20Resources.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/05.%20Responses.md)
+ [Next: Requests](06.%20Requests.md)
# Group Messages
Group of all messages-related resources.
## My Message [/message]
### Retrieve a Message [GET]
This action has **two** responses defined: One returning plain text and the
other a JSON representation of our resource. Both have the same HTTP status
code. Also both responses bear additional information in the form of a custom
HTTP header. Note that both responses have set the `Content-Type` HTTP header
just by specifying `(text/plain)` or `(application/json)` in their respective
signatures.
+ Response 200 (text/plain)
+ Headers
X-My-Message-Header: 42
+ Body
Hello World!
+ Response 200 (application/json)
+ Headers
X-My-Message-Header: 42
+ Body
{ "message": "Hello World!" }
### Update a Message [PUT]
+ Request (text/plain)
All your base are belong to us.
+ Response 204
================================================
FILE: examples/06. Requests.md
================================================
FORMAT: 1A
# Requests API
Following the [Responses](05.%20Responses.md) example, this API will show you
how to define multiple requests and what data these requests can bear. Let's
demonstrate multiple requests on a trivial example of content negotiation.
## API Blueprint
+ [Previous: Responses](05.%20Responses.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/06.%20Requests.md)
+ [Next: Parameters](07.%20Parameters.md)
# Group Messages
Group of all messages-related resources.
## My Message [/message]
### Retrieve a Message [GET]
In API Blueprint, _requests_ can hold exactly the same kind of information and
can be described using exactly the same structure as _responses_, only with
different signature – using the `Request` keyword. The string that follows
after the `Request` keyword is a request identifier. Again, using explanatory
and simple naming is the best way to go.
+ Request Plain Text Message
+ Headers
Accept: text/plain
+ Response 200 (text/plain)
+ Headers
X-My-Message-Header: 42
+ Body
Hello World!
+ Request JSON Message
+ Headers
Accept: application/json
+ Response 200 (application/json)
+ Headers
X-My-Message-Header: 42
+ Body
{ "message": "Hello World!" }
### Update a Message [PUT]
+ Request Update Plain Text Message (text/plain)
All your base are belong to us.
+ Request Update JSON Message (application/json)
{ "message": "All your base are belong to us." }
+ Response 204
================================================
FILE: examples/07. Parameters.md
================================================
FORMAT: 1A
# Parameters API
In this installment of the API Blueprint course we will discuss how to describe URI parameters.
But first let's add more messages to our system. For that we would need
introduce an message identifier – id. This id will be our parameter when
communicating with our API about messages.
## API Blueprint
+ [Previous: Requests](06.%20Requests.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/07.%20Parameters.md)
+ [Next: Attributes](08.%20Attributes.md)
# Group Messages
Group of all messages-related resources.
## My Message [/message/{id}]
Here we have added the message `id` parameter as an
[URI Template variable](http://tools.ietf.org/html/rfc6570) in the Message
resource's URI. Note the parameter name `id` is enclosed in curly brackets. We
will discuss this parameter in the `Parameters` section below, where we will
also set its example value to `1` and declare it of an arbitrary 'number' type.
+ Parameters
+ id: 1 (number) - An unique identifier of the message.
### Retrieve a Message [GET]
+ Request Plain Text Message
+ Headers
Accept: text/plain
+ Response 200 (text/plain)
+ Headers
X-My-Message-Header: 42
+ Body
Hello World!
+ Request JSON Message
+ Headers
Accept: application/json
+ Response 200 (application/json)
+ Headers
X-My-Message-Header: 42
+ Body
{
"id": 1,
"message": "Hello World!"
}
### Update a Message [PUT]
+ Request Update Plain Text Message (text/plain)
All your base are belong to us.
+ Request Update JSON Message (application/json)
{ "message": "All your base are belong to us." }
+ Response 204
## All My Messages [/messages{?limit}]
A resource representing all of my messages in the system.
We have added the query URI template parameter - `limit`. This parameter is
used for limiting the number of results returned by some actions on this
resource. It does not affect every possible action of this resource, therefore
we will discuss it only at the particular action level below.
### Retrieve all Messages [GET]
+ Parameters
+ limit (number, optional) - The maximum number of results to return.
+ Default: `20`
+ Response 200 (application/json)
[
{
"id": 1,
"message": "Hello World!"
},
{
"id": 2,
"message": "Time is an illusion. Lunchtime doubly so."
},
{
"id": 3,
"message": "So long, and thanks for all the fish."
}
]
================================================
FILE: examples/08. Attributes.md
================================================
FORMAT: 1A
# Attributes API
This API example demonstrates how to describe body attributes of a request or
response message.
In this case, the description is complementary (and duplicate!) to the provided
JSON example in the body section. The
[Advanced Attributes](09.%20Advanced%20Attributes.md) API example will
demonstrate how to avoid duplicates and how to reuse attribute descriptions.
## API Blueprint
+ [Previous: Parameters](07.%20Parameters.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/08.%20Attributes.md)
+ [Next: Advanced Attributes](09.%20Advanced%20Attributes.md)
# Group Coupons
## Coupon [/coupons/{id}]
A coupon contains information about a percent-off or amount-off discount you
might want to apply to a customer.
### Retrieve a Coupon [GET]
Retrieves the coupon with the given ID.
+ Response 200 (application/json)
+ Attributes (object)
+ id: 250FF (string, required)
+ created: 1415203908 (number) - Time stamp
+ percent_off: 25 (number)
A positive integer between 1 and 100 that represents the discount
the coupon will apply.
+ redeem_by (number) - Date after which the coupon can no longer be redeemed
+ Body
{
"id": "250FF",
"created": 1415203908,
"percent_off": 25,
"redeem_by": null
}
================================================
FILE: examples/09. Advanced Attributes.md
================================================
FORMAT: 1A
# Advanced Attributes API
Improving the previous [Attributes](08.%20Attributes.md) description example,
this API example describes the `Coupon` resource attributes (data structure)
regardless of the serialization format. These attributes can be later
referenced using the resource name.
These attributes are then reused in the `Retrieve a Coupon` action. Since they
describe the complete message, no explicit JSON body example is needed.
Moving forward, the `Coupon` resource data structure is then reused when
defining the attributes of the coupons collection resource – `Coupons`.
The `Create a Coupon` action also demonstrate the description of request
attributes – once defined, these attributes are implied on every `Create a
Coupon` request unless the request specifies otherwise. Apparently, the
description of action attributes is somewhat duplicate to the definition of
`Coupon` resource attributes. We will address this in the next
[Data Structures](10.%20Data%20Structures.md) example.
## API Blueprint
+ [Previous: Attributes](08.%20Attributes.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/09.%20Advanced%20Attributes.md)
+ [Next: Data Structures](10.%20Data%20Structures.md)
# Group Coupons
## Coupon [/coupons/{id}]
A coupon contains information about a percent-off or amount-off discount you
might want to apply to a customer.
+ Parameters
+ id (string)
The ID of the desired coupon.
+ Attributes (object)
+ id: 250FF (string, required)
+ created: 1415203908 (number) - Time stamp
+ percent_off: 25 (number)
A positive integer between 1 and 100 that represents the discount the coupon will apply.
+ redeem_by (number) - Date after which the coupon can no longer be redeemed
### Retrieve a Coupon [GET]
Retrieves the coupon with the given ID.
+ Response 200 (application/json)
+ Attributes (Coupon)
## Coupons [/coupons{?limit}]
+ Attributes (array[Coupon])
### List all Coupons [GET]
Returns a list of your coupons.
+ Parameters
+ limit (number, optional)
A limit on the number of objects to be returned. Limit can range
between 1 and 100 items.
+ Default: `10`
+ Response 200 (application/json)
+ Attributes (Coupons)
### Create a Coupon [POST]
Creates a new Coupon.
+ Attributes (object)
+ percent_off: 25 (number)
+ redeem_by (number)
+ Request (application/json)
+ Response 200 (application/json)
+ Attributes (Coupon)
================================================
FILE: examples/10. Data Structures.md
================================================
FORMAT: 1A
# Data Structures API
Following [Advanced Attributes](09.%20Advanced%20Attributes.md), this example
demonstrates defining arbitrary data structure to be reused by various
attribute descriptions.
Since a portion of the `Coupon` data structure is shared between the `Coupon`
definition itself and the `Create a Coupon` action, it was separated into a
`Coupon Base` data structure in the `Data Structures` API Blueprint Section.
Doing so enables us to reuse it as a base-type of other attribute definitions.
## API Blueprint
+ [Previous: Advanced Attributes](09.%20Advanced%20Attributes.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/10.%20Data%20Structures.md)
+ [Next: Resource Model](11.%20Resource%20Model.md)
# Group Coupons
## Coupon [/coupons/{id}]
A coupon contains information about a percent-off or amount-off discount you
might want to apply to a customer.
+ Parameters
+ id (string)
The ID of the desired coupon.
+ Attributes (Coupon Base)
+ id: 250FF (string, required)
+ created: 1415203908 (number) - Time stamp
### Retrieve a Coupon [GET]
Retrieves the coupon with the given ID.
+ Response 200 (application/json)
+ Attributes (Coupon)
## Coupons [/coupons{?limit}]
+ Attributes (array[Coupon])
### List all Coupons [GET]
Returns a list of your coupons.
+ Parameters
+ limit (number, optional)
A limit on the number of objects to be returned. Limit can range
between 1 and 100 items.
+ Default: `10`
+ Response 200 (application/json)
+ Attributes (Coupons)
### Create a Coupon [POST]
Creates a new Coupon.
+ Attributes (Coupon Base)
+ Request (application/json)
+ Response 200 (application/json)
+ Attributes (Coupon)
# Data Structures
## Coupon Base (object)
+ percent_off: 25 (number)
A positive integer between 1 and 100 that represents the discount the
coupon will apply.
+ redeem_by (number) - Date after which the coupon can no longer be redeemed
================================================
FILE: examples/11. Resource Model.md
================================================
FORMAT: 1A
# Resource Model API
Resource model is a [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation).
One particular representation of your resource.
Furthermore, in API Blueprint, any `resource model` you have defined can be
referenced in a request or response section, saving you lots of time
maintaining your API blueprint. You simply define a resource model as any
payload (e.g. [request](https://github.com/apiaryio/api-blueprint/blob/master/examples/06.%20Requests.md)
or [response](https://github.com/apiaryio/api-blueprint/blob/master/examples/5.%20Responses.md))
and then reference it later where you would normally write a `request` or
`response`.
## API Blueprint
+ [Previous: Data Structures](10.%20Data%20Structures.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/11.%20Resource%20Model.md)
+ [Next: Advanced Action](12.%20Advanced%20Action.md)
# Group Messages
Group of all messages-related resources.
## My Message [/message]
+ Model (application/vnd.siren+json)
This is the `application/vnd.siren+json` message resource representation.
+ Headers
Location: http://api.acme.com/message
+ Body
{
"class": [ "message" ],
"properties": {
"message": "Hello World!"
},
"links": [
{ "rel": "self" , "href": "/message" }
]
}
### Retrieve a Message [GET]
At this point we will utilize our `Message` resource model and reference it in
`Response 200`.
+ Response 200
[My Message][]
### Update a Message [PUT]
+ Request Update Plain Text Message (text/plain)
All your base are belong to us.
+ Request Update JSON Message (application/json)
{ "message": "All your base are belong to us." }
+ Response 204
================================================
FILE: examples/12. Advanced Action.md
================================================
FORMAT: 1A
# Advanced Action API
A resource action is – in fact – a state transition. This API example
demonstrates an action - state transition - to another resource.
## API Blueprint
+ [Previous: Resource Model](11.%20Resource%20Model.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/12.%20Advanced%20Action.md)
+ [Next: Named Endpoints](13.%20Named%20Endpoints.md)
# Tasks [/tasks/tasks{?status,priority}]
+ Parameters
+ status (string)
+ priority (number)
## List All Tasks [GET]
+ Response 200 (application/json)
[
{
"id": 123,
"name": "Exercise in gym",
"done": false,
"type": "task"
},
{
"id": 124,
"name": "Shop for groceries",
"done": true,
"type": "task"
}
]
## Retrieve Task [GET /task/{id}]
This is a state transition to another resource.
+ Parameters
+ id (string)
+ Response 200 (application/json)
{
"id": 123,
"name": "Go to gym",
"done": false,
"type": "task"
}
## Delete Task [DELETE /task/{id}]
+ Parameters
+ id (string)
+ Response 204
================================================
FILE: examples/13. Named Endpoints.md
================================================
FORMAT: 1A
# Named Endpoints API
This API example demonstrates how to define a standalone endpoint with an identifier.
## API Blueprint
+ [Previous: Advanced Action](12.%20Advanced%20Action.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/13.%20Named%20Endpoints.md)
+ [Next: JSON Schema](14.%20JSON%20Schema.md)
# Group Quick start
## Create message [POST /messages]
Start out by creating a message for the world to see.
+ Request (application/json)
{ "message": "Hello World!" }
+ Response 201
+ Headers
Location: /messages/1337
## Create a new task [POST /tasks]
Now create a task that you need to do at a later date.
+ Request (application/json)
{
"name": "Exercise in gym",
"done": false,
"type": "task"
}
+ Response 201
+ Headers
Location: /tasks/1992
================================================
FILE: examples/14. JSON Schema.md
================================================
FORMAT: 1A
# JSON Schema
Every request and response can have a schema. Below you will find examples
using [JSON Schema](http://json-schema.org/) to describe the format of request
and response body content.
## API Blueprint
+ [Previous: Named Endpoints](13.%20Named%20Endpoints.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/14.%20JSON%20Schema.md)
+ [Next: Advanced JSON Schema](15.%20Advanced%20JSON%20Schema.md)
# Notes [/notes/{id}]
+ Parameters
+ id: abc123 (required) - Unique identifier for a note
## Get a note [GET]
Gets a single note by its unique identifier.
+ Response 200 (application/json)
+ Body
{
"id": "abc123",
"title": "This is a note",
"content": "This is the note content."
"tags": [
"todo",
"home"
]
}
+ Schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
## Update a note [PATCH]
Modify a note's data using its unique identifier. You can edit the `title`,
`content`, and `tags`.
+ Request (application/json)
+ Body
{
"title": "This is another note",
"tags": [
"todo",
"work"
]
}
+ Schema
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
+ Response 204
================================================
FILE: examples/15. Advanced JSON Schema.md
================================================
FORMAT: 1A
# Advanced JSON Schema
The JSON body and JSON Schema for a request or response can be generated from
the attributes section MSON data structure. The generated schema can also be
overridden by providing an explicit schema, as you can see in the examples
below.
## API Blueprint
+ [Previous: JSON Schema](14.%20JSON%20Schema.md)
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/15.%20Advanced%20JSON%20Schema.md)
# Notes [/notes/{id}]
+ Parameters
+ id: abc123 (required) - Unique identifier for a note
## Get a note [GET]
Gets a single note by its unique identifier.
+ Response 200 (application/json)
+ Attributes
+ id: abc123
+ title: This is a note
+ content: This is the note content.
+ tags: todo, home (array[string])
## Update a note [PATCH]
Modify a note's data using its unique identifier. You can edit the `title`,
`content`, and `tags`.
+ Request (application/json)
+ Attributes
+ title: This is another note
+ content
+ tags: todo, work (array[string])
+ Schema
{
"type": "object",
"description": "This is a custom schema!",
"properties": {
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
+ Response 204
================================================
FILE: examples/Gist Fox API + Auth.md
================================================
FORMAT: 1A
# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).
## Authentication
*Gist Fox API* uses OAuth Authorization. First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token' scope.
## Media Types
Where applicable this API uses the [HAL+JSON](https://github.com/mikekelly/hal_specification/blob/master/hal_specification.md) media-type to represent resources states and affordances.
Requests with a message-body are using plain JSON to set or update resource states.
## Error States
The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.
# Gist Fox API Root [/]
Gist Fox API entry point.
This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and
HAL links.
## Retrieve the Entry Point [GET]
+ Response 200 (application/hal+json)
+ Headers
Link: <http:/api.gistfox.com/>;rel="self",<http:/api.gistfox.com/gists>;rel="gists",<http:/api.gistfox.com/authorization>;rel="authorization"
+ Body
{
"_links": {
"self": { "href": "/" },
"gists": { "href": "/gists?{since}", "templated": true },
"authorization": { "href": "/authorization"}
}
}
# Group Gist
Gist-related resources of *Gist Fox API*.
## Gist [/gists/{id}{?access_token}]
A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note.
The Gist resource has the following attributes:
+ id
+ created_at
+ description
+ content
The states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation.
+ Parameters
+ id (string) - ID of the Gist in the form of a hash.
+ access_token (string, optional) - Gist Fox API access token.
+ Model (application/hal+json)
HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links.
+ Headers
Link: <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"
+ Body
{
"_links": {
"self": { "href": "/gists/42" },
"star": { "href": "/gists/42/star" },
},
"id": "42",
"created_at": "2014-04-14T02:15:15Z",
"description": "Description of Gist",
"content": "String contents"
}
### Retrieve a Single Gist [GET]
+ Response 200
[Gist][]
### Edit a Gist [PATCH]
To update a Gist send a JSON with updated value for one or more of the Gist resource attributes. All attributes values (states) from the previous version of this Gist are carried over by default if not included in the hash.
+ Request (application/json)
{
"content": "Updated file contents"
}
+ Response 200
[Gist][]
### Delete a Gist [DELETE]
+ Response 204
## Gists Collection [/gists{?access_token,since}]
Collection of all Gists.
The Gist Collection resource has the following attribute:
+ total
In addition it **embeds** *Gist Resources* in the Gist Fox API.
+ Model (application/hal+json)
HAL+JSON representation of Gist Collection Resource. The Gist resources in collections are embedded. Note the embedded Gists resource are incomplete representations of the Gist in question. Use the respective Gist link to retrieve its full representation.
+ Headers
Link: <http:/api.gistfox.com/gists>;rel="self"
+ Body
{
"_links": {
"self": { "href": "/gists" }
},
"_embedded": {
"gists": [
{
"_links" : {
"self": { "href": "/gists/42" }
},
"id": "42",
"created_at": "2014-04-14T02:15:15Z",
"description": "Description of Gist"
}
]
},
"total": 1
}
### List All Gists [GET]
+ Parameters
+ since (string, optional) - Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.
+ Response 200
[Gists Collection][]
### Create a Gist [POST]
To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist.
This action requires an `access_token` with `gist_write` scope.
+ Parameters
+ access_token (string, optional) - Gist Fox API access token.
+ Request (application/json)
{
"description": "Description of Gist",
"content": "String content"
}
+ Response 201
[Gist][]
## Star [/gists/{id}/star{?access_token}]
Star resource represents a Gist starred status.
The Star resource has the following attribute:
+ starred
+ Parameters
+ id (string) - ID of the gist in the form of a hash
+ access_token (string, optional) - Gist Fox API access token.
+ Model (application/hal+json)
HAL+JSON representation of Star Resource.
+ Headers
Link: <http:/api.gistfox.com/gists/42/star>;rel="self"
+ Body
{
"_links": {
"self": { "href": "/gists/42/star" },
},
"starred": true
}
### Star a Gist [PUT]
This action requires an `access_token` with `gist_write` scope.
+ Response 204
### Unstar a Gist [DELETE]
This action requires an `access_token` with `gist_write` scope.
+ Response 204
### Check if a Gist is Starred [GET]
+ Response 200
[Star][]
# Group Access Authorization and Control
Access and Control of *Gist Fox API* OAuth token.
## Authorization [/authorization]
Authorization Resource represents an authorization granted to the user. You can **only** access your own authorization, and only through **Basic Authentication**.
The Authorization Resource has the following attribute:
+ token
+ scopes
Where *token* represents an OAuth token and *scopes* is an array of scopes granted for the given authorization. At this moment the only available scope is `gist_write`.
+ Model (application/hal+json)
+ Headers
Link: <http:/api.gistfox.com/authorizations/1>;rel="self"
+ Body
{
"_links": {
"self": { "href": "/authorizations" },
},
"scopes": [
"gist_write"
],
"token": "abc123"
}
### Retrieve Authorization [GET]
+ Request
+ Headers
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+ Response 200
[Authorization][]
### Create Authorization [POST]
+ Request (application/json)
+ Headers
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+ Body
{
"scopes": [
"gist_write"
]
}
+ Response 201
[Authorization][]
### Remove an Authorization [DELETE]
+ Request
+ Headers
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+ Response 204
================================================
FILE: examples/Gist Fox API.md
================================================
FORMAT: 1A
# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).
## Authentication
Currently the Gist Fox API does not provide authenticated access.
## Media Types
Where applicable this API uses the [HAL+JSON](https://github.com/mikekelly/hal_specification/blob/master/hal_specification.md) media-type to represent resources states and affordances.
Requests with a message-body are using plain JSON to set or update resource states.
## Error States
The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.
# Gist Fox API Root [/]
Gist Fox API entry point.
This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and
HAL links.
## Retrieve the Entry Point [GET]
+ Response 200 (application/hal+json)
+ Headers
Link: <http:/api.gistfox.com/>;rel="self",<http:/api.gistfox.com/gists>;rel="gists"
+ Body
{
"_links": {
"self": { "href": "/" },
"gists": { "href": "/gists?{since}", "templated": true }
}
}
# Group Gist
Gist-related resources of *Gist Fox API*.
## Gist [/gists/{id}]
A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note.
The Gist resource has the following attributes:
+ id
+ created_at
+ description
+ content
The states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation.
+ Parameters
+ id (string) - ID of the Gist in the form of a hash.
+ Model (application/hal+json)
HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links.
+ Headers
Link: <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"
+ Body
{
"_links": {
"self": { "href": "/gists/42" },
"star": { "href": "/gists/42/star" }
},
"id": "42",
"created_at": "2014-04-14T02:15:15Z",
"description": "Description of Gist",
"content": "String contents"
}
### Retrieve a Single Gist [GET]
+ Response 200
[Gist][]
### Edit a Gist [PATCH]
To update a Gist send a JSON with updated value for one or more of the Gist resource attributes. All attributes values (states) from the previous version of this Gist are carried over by default if not included in the hash.
+ Request (application/json)
{
"content": "Updated file contents"
}
+ Response 200
[Gist][]
### Delete a Gist [DELETE]
+ Response 204
## Gists Collection [/gists{?since}]
Collection of all Gists.
The Gist Collection resource has the following attribute:
+ total
In addition it **embeds** *Gist Resources* in the Gist Fox API.
+ Model (application/hal+json)
HAL+JSON representation of Gist Collection Resource. The Gist resources in collections are embedded. Note the embedded Gists resource are incomplete representations of the Gist in question. Use the respective Gist link to retrieve its full representation.
+ Headers
Link: <http:/api.gistfox.com/gists>;rel="self"
+ Body
{
"_links": {
"self": { "href": "/gists" }
},
"_embedded": {
"gists": [
{
"_links" : {
"self": { "href": "/gists/42" }
},
"id": "42",
"created_at": "2014-04-14T02:15:15Z",
"description": "Description of Gist"
}
]
},
"total": 1
}
### List All Gists [GET]
+ Parameters
+ since (string, optional) - Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.
+ Response 200
[Gists Collection][]
### Create a Gist [POST]
To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist.
+ Request (application/json)
{
"description": "Description of Gist",
"content": "String content"
}
+ Response 201
[Gist][]
## Star [/gists/{id}/star]
Star resource represents a Gist starred status.
The Star resource has the following attribute:
+ starred
+ Parameters
+ id (string) - ID of the gist in the form of a hash
+ Model (application/hal+json)
HAL+JSON representation of Star Resource.
+ Headers
Link: <http:/api.gistfox.com/gists/42/star>;rel="self"
+ Body
{
"_links": {
"self": { "href": "/gists/42/star" }
},
"starred": true
}
### Star a Gist [PUT]
+ Response 204
### Unstar a Gist [DELETE]
+ Response 204
### Check if a Gist is Starred [GET]
+ Response 200
[Star][]
================================================
FILE: examples/Polls API.md
================================================
FORMAT: 1A
HOST: http://polls.apiblueprint.org/
# Polls
Polls is a simple API allowing consumers to view polls and vote in them. You can view this documentation over at [Apiary](http://docs.pollsapi.apiary.io).
# Polls API Root [/]
This resource does not have any attributes. Instead it offers the initial API affordances in the form of the links in the JSON body.
It is recommended to follow the “url” link values, [Link](https://tools.ietf.org/html/rfc5988) or Location headers where applicable to retrieve resources. Instead of constructing your own URLs, to keep your client decoupled from implementation details.
## Retrieve the Entry Point [GET]
+ Response 200 (application/json)
{
"questions_url": "/questions"
}
## Group Question
Resources related to questions in the API.
## Question [/questions/{question_id}]
A Question object has the following attributes:
+ question
+ published_at - An ISO8601 date when the question was published.
+ url
+ choices - An array of Choice objects.
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
### 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
}
]
}
## Choice [/questions/{question_id}/choices/{choice_id}]
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
+ choice_id: 1 (required, number) - ID of the Choice in form of an integer
### Vote on a Choice [POST]
This action allows you to vote on a question's choice.
+ Response 201
+ Headers
Location: /questions/1
## Questions Collection [/questions{?page}]
+ Parameters
+ page: 1 (optional, number) - The page of questions to return
### List All Questions [GET]
+ Response 200 (application/json)
+ Headers
Link: </questions?page=2>; rel="next"
+ 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": 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
}
]
}
]
### 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.
+ Request (application/json)
{
"question": "Favourite programming language?",
"choices": [
"Swift",
"Python",
"Objective-C",
"Ruby"
]
}
+ Response 201 (application/json)
+ Headers
Location: /questions/2
+ Body
{
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z",
"url": "/questions/2",
"choices": [
{
"choice": "Swift",
"url": "/questions/2/choices/1",
"votes": 0
}, {
"choice": "Python",
"url": "/questions/2/choices/2",
"votes": 0
}, {
"choice": "Objective-C",
"url": "/questions/2/choices/3",
"votes": 0
}, {
"choice": "Ruby",
"url": "/questions/2/choices/4",
"votes": 0
}
]
}
================================================
FILE: examples/Polls Hypermedia API.md
================================================
FORMAT: 1A
HOST: http://polls.apiblueprint.org/
# Polls
Polls is a simple API allowing consumers to view polls and vote in them. You can view this documentation over at [Apiary](http://docs.pollshypermedia.apiary.io/).
# Polls API Root [/]
This resource does not have any attributes. Instead it offers the initial API affordances.
## Retrieve the Entry Point [GET]
+ Response 200 (application/vnd.siren+json)
{
"links": [
{
"rel": [ "questions" ],
"href": "/questions"
}
]
}
+ Response 200 (application/hal+json)
{
"_links": {
"questions": { "href": "/questions" }
}
}
## Questions Collection [/questions{?page}]
+ Parameters
+ page: 1 (optional, number) - The page of questions to return
### List All Questions [GET]
+ Relation: questions
+ Response 200 (application/vnd.siren+json)
{
"actions": [
{
"name": "add",
"href": "/questions",
"method": "POST",
"type": "application/json",
"fields": [
{
"name": "question"
}, {
"name": "choices"
}
]
}
],
"links": [
{
"rel": [ "next" ],
"href": "/questions?page=2"
},
{
"rel": [ "self" ],
"href": "/questions"
}
],
"entities": [
{
"actions": [
{
"name": "delete",
"href": "/questions/1",
"method": "DELETE"
}
],
"rel": [ "question" ],
"properties": {
"published_at": "2014-11-11T08:40:51.620Z",
"question": "Favourite programming language?"
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1"
}
],
"entities": [
{
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/1",
"method": "POST"
}
],
"rel": [ "choice" ],
"properties": {
"choice": "Swift",
"votes": 2048
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/1"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/2",
"method": "POST"
}
],
"rel": [ "choice" ],
"properties": {
"choice": "Python",
"votes": 1024
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/2"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/3",
"method": "POST"
}
],
"rel": [ "choice" ],
"properties": {
"choice": "Objective-C",
"votes": 512
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/3"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/4",
"method": "POST"
}
],
"rel": [ "choice" ],
"properties": {
"choice": "Ruby",
"votes": 256
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/4"
}
]
}
]
}
]
}
+ Response 200 (application/hal+json)
{
"_links": {
"self": { "href": "/questions" },
"next": { "href": "/questions?page=2" }
},
"_embedded": {
"question": [
{
"_links": {
"self": { "self": "/questions/1" }
},
"_embedded": {
"choice": [
{
"_links": {
"self": { "self": "/questions/1/choices/1" }
},
"choice": "Swift",
"votes": 2048
}, {
"_links": {
"self": { "self": "/questions/1/choices/2" }
},
"choice": "Python",
"votes": 1024
}, {
"_links": {
"self": { "self": "/questions/1/choices/3" }
},
"choice": "Objective-C",
"votes": 512
}, {
"_links": {
"self": { "self": "/questions/1/choices/4" }
},
"choice": "Ruby",
"votes": 256
}
]
},
"question": "Favourite programming language?",
"published_at": "2014-11-11T08:40:51.620Z"
}
]
}
}
### 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.
+ Relation: create
+ Request (application/json)
{
"question": "Favourite programming language?",
"choices": [
"Swift",
"Python",
"Objective-C",
"Ruby"
]
}
+ Response 201 (application/vnd.siren+json)
{
"actions": [
{
"name": "delete",
"href": "/questions/1",
"method": "DELETE"
}
],
"properties": {
"published_at": "2014-11-11T08:40:51.620Z",
"question": "Favourite programming language?"
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1"
}
],
"entities": [
{
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/1",
"method": "POST"
}
],
"rel": [ "choices" ],
"properties": {
"choice": "Swift",
"votes": 2048
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/1"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/2",
"method": "POST"
}
],
"rel": [ "choices" ],
"properties": {
"choice": "Python",
"votes": 1024
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/2"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/3",
"method": "POST"
}
],
"rel": [ "choices" ],
"properties": {
"choice": "Objective-C",
"votes": 512
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/3"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/4",
"method": "POST"
}
],
"rel": [ "choices" ],
"properties": {
"choice": "Ruby",
"votes": 256
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/4"
}
]
}
]
}
+ Response 201 (application/hal+json)
{
"_links": {
"self": { "href": "/questions/1" }
},
"_embedded": {
"choices": [
{
"_links": {
"self": { "self": "/questions/1/choices/1" }
},
"choice": "Swift",
"votes": 2048
}, {
"_links": {
"self": { "self": "/questions/1/choices/2" }
},
"choice": "Python",
"votes": 1024
}, {
"_links": {
"self": { "self": "/questions/1/choices/3" }
},
"choice": "Objective-C",
"votes": 512
}, {
"_links": {
"self": { "self": "/questions/1/choices/4" }
},
"choice": "Ruby",
"votes": 256
}
]
},
"published_at": "2014-11-11T08:40:51.620Z",
"question": "Favourite programming language?"
}
## Group Question
Resources related to questions in the API.
## Question [/questions/{question_id}]
A Question object has the following attributes:
+ question
+ published_at - An ISO8601 date when the question was published.
+ url
+ choices - An array of Choice objects.
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
### View a Questions Detail [GET]
+ Relation: question
+ Response 200 (application/vnd.siren+json)
{
"actions": [
{
"name": "delete",
"href": "/questions/1",
"method": "DELETE"
}
],
"properties": {
"published_at": "2014-11-11T08:40:51.620Z",
"question": "Favourite programming language?"
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1"
}
],
"entities": [
{
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/1",
"method": "POST"
}
],
"rel": [ "choices" ],
"properties": {
"choice": "Swift",
"votes": 2048
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/1"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/2",
"method": "POST"
}
],
"rel": [ "choices" ],
"properties": {
"choice": "Python",
"votes": 1024
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/2"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/3",
"method": "POST"
}
],
"rel": [ "choices" ],
"properties": {
"choice": "Objective-C",
"votes": 512
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/3"
}
]
}, {
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/4",
"method": "POST"
}
],
"rel": [ "choices" ],
"properties": {
"choice": "Ruby",
"votes": 256
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/4"
}
]
}
]
}
+ Response 200 (application/hal+json)
{
"_links": {
"self": { "href": "/questions/1" }
},
"_embedded": {
"choices": [
{
"_links": {
"self": { "self": "/questions/1/choices/1" }
},
"choice": "Swift",
"votes": 2048
}, {
"_links": {
"self": { "self": "/questions/1/choices/2" }
},
"choice": "Python",
"votes": 1024
}, {
"_links": {
"self": { "self": "/questions/1/choices/3" }
},
"choice": "Objective-C",
"votes": 512
}, {
"_links": {
"self": { "self": "/questions/1/choices/4" }
},
"choice": "Ruby",
"votes": 256
}
]
},
"published_at": "2014-11-11T08:40:51.620Z",
"question": "Favourite programming language?"
}
## Choice [/questions/{question_id}/choices/{choice_id}]
+ Parameters
+ question_id: 1 (required, number) - ID of the Question in form of an integer
+ choice_id: 1 (required, number) - ID of the Choice in form of an integer
### View a Choice Detail [GET]
+ Relation: choice
+ Response 200 (application/vnd.siren+json)
{
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/1",
"method": "POST"
}
],
"rel": [ "choice" ],
"properties": {
"choice": "Swift",
"votes": 2048
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/1"
}
]
}
+ Response 200 (application/hal+json)
{
"_links": {
"self": { "href": "/questions/1/choices/1" }
},
"choice": "Swift",
"votes": 2048
}
### Vote on a Choice [POST]
This action allows you to vote on a question's choice.
+ Relation: vote
+ Response 201 (application/vnd.siren+json)
{
"actions": [
{
"name": "vote",
"href": "/questions/1/choices/1",
"method": "POST"
}
],
"rel": [ "choice" ],
"properties": {
"choice": "Swift",
"votes": 2049
},
"links": [
{
"rel": [ "self" ],
"href": "/questions/1/choices/1"
}
]
}
+ Response 201 (application/hal+json)
{
"_links": {
"self": "/questions/1/choices/1"
},
"choice": "Swift",
"votes": 2049
}
================================================
FILE: examples/README.md
================================================
# API Blueprint Examples
All files in this directory are actual **valid API blueprints**. Since they are saved with the `.md` extension GitHub automatically renders them during viewing.
**To view an API blueprint source make sure to view the file as "raw".**
================================================
FILE: examples/Real World API.md
================================================
FORMAT: 1A
HOST: https://alpha-api.app.net
# Real World API
This API Blueprint demonstrates a real world example documenting a portion of
[App.net API](http://developers.app.net).
NOTE: This document is a **work in progress**.
# Group Posts
This section groups App.net post resources.
## Post [/stream/0/posts/{post_id}]
A Post is the other central object utilized by the App.net Stream API. It has
rich text and annotations which comprise all of the content a users sees in
their feed. Posts are closely tied to the follow graph...
+ Parameters
+ post_id: `1` (string) - The id of the Post.
+ Model (application/json)
```js
{
"data": {
"id": "1", // note this is a string
"user": {
...
},
"created_at": "2012-07-16T17:25:47Z",
"text": "@berg FIRST post on this new site #newsocialnetwork",
"html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
"source": {
"client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4",
"name": "Clientastic for iOS",
"link": "http://app.net"
},
"machine_only": false,
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
"num_reposts": 0,
"num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
"id": "2",
"pos": 0,
"len": 5
}],
"hashtags": [{
"name": "newsocialnetwork",
"pos": 34,
"len": 17
}],
"links": [{
"text": "this new site",
"url": "https://join.app.net"
"pos": 20,
"len": 13
}]
},
"you_reposted": false,
"you_starred": false
},
"meta": {
"code": 200,
}
}
```
### Retrieve a Post [GET]
Returns a specific Post.
+ Response 200
[Post][]
### Delete a Post [DELETE]
Delete a Post. The current user must be the same user who created the Post. It
returns the deleted Post on success.
+ Response 204
## Posts Collection [/stream/0/posts]
A Collection of posts.
+ Model (application/json)
```js
{
"data": [
{
"id": "1", // note this is a string
...
},
{
"id": "2",
...
},
{
"id": "3",
...
},
],
"meta": {
"code": 200,
}
}
```
### Create a Post [POST]
Create a new Post object. Mentions and hashtags will be parsed out of the post
text, as will bare URLs...
+ Request
[Post][]
+ Response 201
[Post][]
### Retrieve all Posts [GET]
Retrieves all posts.
+ Response 200
[Posts Collection][]
## Stars [/stream/0/posts/{post_id}/star]
A User’s stars are visible to others, but they are not automatically added to
your followers’ streams.
+ Parameters
+ post_id: `1` (string) - The id of the Post.
### Star a Post [POST]
Save a given Post to the current User’s stars. This is just a “save” action,
not a sharing action.
*Note: A repost cannot be starred. Please star the parent Post.*
+ Response 200
[Post][]
### Unstar a Post [DELETE]
Remove a Star from a Post.
+ Response 200
[Post][]
gitextract_jtccfgkk/
├── .gitignore
├── API Blueprint Specification.md
├── Advanced Tutorial.md
├── Glossary of Terms.md
├── LICENSE
├── README.md
├── Tutorial.md
└── examples/
├── 01. Simplest API.md
├── 02. Resource and Actions.md
├── 03. Named Resource and Actions.md
├── 04. Grouping Resources.md
├── 05. Responses.md
├── 06. Requests.md
├── 07. Parameters.md
├── 08. Attributes.md
├── 09. Advanced Attributes.md
├── 10. Data Structures.md
├── 11. Resource Model.md
├── 12. Advanced Action.md
├── 13. Named Endpoints.md
├── 14. JSON Schema.md
├── 15. Advanced JSON Schema.md
├── Gist Fox API + Auth.md
├── Gist Fox API.md
├── Polls API.md
├── Polls Hypermedia API.md
├── README.md
└── Real World API.md
Condensed preview — 28 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (141K chars).
[
{
"path": ".gitignore",
"chars": 42,
"preview": "_site\nnode_modules\n.DS_Store\nnpm-debug.log"
},
{
"path": "API Blueprint Specification.md",
"chars": 40146,
"preview": "---\n\nAuthor: z@apiary.io\nVersion: 1A9\n\n---\n\n# API Blueprint\n#### Format 1A revision 9\n\n## [I. API Blueprint Language](#d"
},
{
"path": "Advanced Tutorial.md",
"chars": 5283,
"preview": "# Advanced API Blueprint Tutorial\n\nWelcome to the advanced API Blueprint tutorial! This tutorial will take you\nthrough a"
},
{
"path": "Glossary of Terms.md",
"chars": 4753,
"preview": "# API Blueprint Glossary of Terms\n\nA brief list of terms as used in the [API Blueprint](http://apiblueprint.org) context"
},
{
"path": "LICENSE",
"chars": 1094,
"preview": "(The MIT License)\n\nCopyright (c) 2014 Apiary Inc. <support@apiary.io>.\n\nPermission is hereby granted, free of charge, to"
},
{
"path": "README.md",
"chars": 3992,
"preview": "\n\n# API Blueprint\n### API Design for Humans\n\nA powerful high-level API design langu"
},
{
"path": "Tutorial.md",
"chars": 10222,
"preview": "# API Blueprint Tutorial\n\nWelcome to an API Blueprint Tutorial! This tutorial will take you through the\nbasics of the AP"
},
{
"path": "examples/01. Simplest API.md",
"chars": 1107,
"preview": "FORMAT: 1A\n\n# The Simplest API\nThis is one of the simplest APIs written in the **API Blueprint**. One plain\nresource com"
},
{
"path": "examples/02. Resource and Actions.md",
"chars": 1649,
"preview": "FORMAT: 1A\n\n# Resource and Actions API\nThis API example demonstrates how to define a resource with multiple actions.\n\n##"
},
{
"path": "examples/03. Named Resource and Actions.md",
"chars": 991,
"preview": "FORMAT: 1A\n\n# Named Resource and Actions API\nThis API example demonstrates how to name a resource and its actions, to gi"
},
{
"path": "examples/04. Grouping Resources.md",
"chars": 1345,
"preview": "FORMAT: 1A\n\n# Grouping Resources API\nThis API example demonstrates how to group resources and form **groups of\nresources"
},
{
"path": "examples/05. Responses.md",
"chars": 1347,
"preview": "FORMAT: 1A\n\n# Responses API\nIn this API example we will discuss what information a response can bear and\nhow to define m"
},
{
"path": "examples/06. Requests.md",
"chars": 1592,
"preview": "FORMAT: 1A\n\n# Requests API\nFollowing the [Responses](05.%20Responses.md) example, this API will show you\nhow to define m"
},
{
"path": "examples/07. Parameters.md",
"chars": 2689,
"preview": "FORMAT: 1A\n\n# Parameters API\nIn this installment of the API Blueprint course we will discuss how to describe URI paramet"
},
{
"path": "examples/08. Attributes.md",
"chars": 1423,
"preview": "FORMAT: 1A\n\n# Attributes API\nThis API example demonstrates how to describe body attributes of a request or\nresponse mess"
},
{
"path": "examples/09. Advanced Attributes.md",
"chars": 2507,
"preview": "FORMAT: 1A\n\n# Advanced Attributes API\nImproving the previous [Attributes](08.%20Attributes.md) description example,\nthis"
},
{
"path": "examples/10. Data Structures.md",
"chars": 2016,
"preview": "FORMAT: 1A\n\n# Data Structures API\nFollowing [Advanced Attributes](09.%20Advanced%20Attributes.md), this example\ndemonstr"
},
{
"path": "examples/11. Resource Model.md",
"chars": 1887,
"preview": "FORMAT: 1A\n\n# Resource Model API\nResource model is a [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resourc"
},
{
"path": "examples/12. Advanced Action.md",
"chars": 1286,
"preview": "FORMAT: 1A\n\n# Advanced Action API\nA resource action is – in fact – a state transition. This API example\ndemonstrates an "
},
{
"path": "examples/13. Named Endpoints.md",
"chars": 912,
"preview": "FORMAT: 1A\n\n# Named Endpoints API\nThis API example demonstrates how to define a standalone endpoint with an identifier.\n"
},
{
"path": "examples/14. JSON Schema.md",
"chars": 2466,
"preview": "FORMAT: 1A\n\n# JSON Schema\nEvery request and response can have a schema. Below you will find examples\nusing [JSON Schema]"
},
{
"path": "examples/15. Advanced JSON Schema.md",
"chars": 1736,
"preview": "FORMAT: 1A\n\n# Advanced JSON Schema\nThe JSON body and JSON Schema for a request or response can be generated from\nthe att"
},
{
"path": "examples/Gist Fox API + Auth.md",
"chars": 7549,
"preview": "FORMAT: 1A\n\n# Gist Fox API\nGist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).\n\n## "
},
{
"path": "examples/Gist Fox API.md",
"chars": 5300,
"preview": "FORMAT: 1A\n\n# Gist Fox API\nGist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).\n\n## "
},
{
"path": "examples/Polls API.md",
"chars": 5237,
"preview": "FORMAT: 1A\nHOST: http://polls.apiblueprint.org/\n\n# Polls\n\nPolls is a simple API allowing consumers to view polls and vot"
},
{
"path": "examples/Polls Hypermedia API.md",
"chars": 20229,
"preview": "FORMAT: 1A\nHOST: http://polls.apiblueprint.org/\n\n# Polls\n\nPolls is a simple API allowing consumers to view polls and vot"
},
{
"path": "examples/README.md",
"chars": 260,
"preview": "# API Blueprint Examples\nAll files in this directory are actual **valid API blueprints**. Since they are saved with the "
},
{
"path": "examples/Real World API.md",
"chars": 3774,
"preview": "FORMAT: 1A\nHOST: https://alpha-api.app.net\n\n# Real World API\nThis API Blueprint demonstrates a real world example docume"
}
]
About this extraction
This page contains the full source code of the apiaryio/api-blueprint GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 28 files (129.7 KB), approximately 30.5k tokens. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.