[
  {
    "path": ".gitignore",
    "content": "_site\nnode_modules\n.DS_Store\nnpm-debug.log"
  },
  {
    "path": "API Blueprint Specification.md",
    "content": "---\n\nAuthor: z@apiary.io\nVersion: 1A9\n\n---\n\n# API Blueprint\n#### Format 1A revision 9\n\n## [I. API Blueprint Language](#def-api-blueprint-language)\n+ [Introduction](#def-introduction)\n+ [API Blueprint](#def-api-blueprint)\n+ [API Blueprint document](#def-api-blueprint-document)\n+ [Blueprint section](#def-blueprint-section)\n    + [Section types](#def-section-types)\n    + [Section structure](#def-section-structure)\n    + [Keywords](#def-keywords)\n    + [Identifier](#def-identifier)\n    + [Description](#def-description)\n    + [Nested sections](#def-nested-sections)\n\n## [II. Sections Reference](#def-sections-reference)\n\n### Abstract\n+ [Named section](#def-named-section)\n+ [Asset section](#def-asset-section)\n+ [Payload section](#def-payload-section)\n\n### Section Basics\n+ [Metadata section](#def-metadata-section)\n+ [API name & overview section](#def-api-name-section)\n+ [Resource group section](#def-resourcegroup-section)\n+ [Resource section](#def-resource-section)\n+ [Resource model section](#def-model-section)\n+ [Schema section](#def-schema-section)\n+ [Action section](#def-action-section)\n+ [Request section](#def-request-section)\n+ [Response section](#def-response-section)\n+ [URI parameters section](#def-uriparameters-section)\n+ [Attributes section](#def-attributes-section)\n+ [Headers section](#def-headers-section)\n+ [Body section](#def-body-section)\n\n### Going Further\n+ [Data Structures section](#def-data-structures)\n+ [Relation section](#def-relation-section)\n\n\n## [III. Appendix](#def-appendix)\n+ [URI Templates](#def-uri-templates)\n\n---\n\n<br>\n\n<a name=\"def-api-blueprint-language\"></a>\n# I. API Blueprint Language\n\n<a name=\"def-introduction\"></a>\n## Introduction\nThis documents is a full specification of the API Blueprint format. For a less\nformal introduction to API Blueprint visit the\n[API Blueprint Tutorial](Tutorial.md) or check some of the [examples][].\n\n<a name=\"def-api-blueprint\"></a>\n## API Blueprint\nAPI Blueprint is a documentation-oriented web API description language. The\nAPI Blueprint is essentially a set of semantic assumptions laid on top of the\nMarkdown syntax used to describe a web API.\n\nIn addition to the regular [Markdown syntax][], API Blueprint conforms to the\n[GitHub Flavored Markdown syntax][].\n\n<a name=\"def-api-blueprint-document\"></a>\n## API Blueprint document\nAn API Blueprint document – a blueprint – is a plain text Markdown document\ndescribing a Web API in whole or in part. The document is structured into\nlogical **sections**. Each section has its distinctive meaning, content and\nposition in the document.\n\nGeneral section definition and structure is discussed in detail later in the\n[Blueprint section](#def-blueprint-section) chapter.\n\nAll of the blueprint sections are optional. However, when present, a section\n**must** follow the API Blueprint **document structure**.\n\n### Blueprint document structure\n\n+ [`0-1` **Metadata** section](#def-metadata-section)\n+ [`0-1` **API Name & overview** section](#def-api-name-section)\n+ [`0+` **Resource** sections](#def-resource-section)\n    + [`0-1` **URI Parameters** section](#def-uriparameters-section)\n    + [`0-1` **Attributes** section](#def-attributes-section)\n    + [`0-1` **Model** section](#def-model-section)\n        + [`0-1` **Headers** section](#def-headers-section)\n        + [`0-1` **Attributes** section](#def-attributes-section)\n        + [`0-1` **Body** section](#def-body-section)\n        + [`0-1` **Schema** section](#def-schema-section)\n    + [`1+` **Action** sections](#def-action-section)\n        + [`0-1` **Relation** section](#def-relation-section)\n        + [`0-1` **URI Parameters** section](#def-uriparameters-section)\n        + [`0-1` **Attributes** section](#def-attributes-section)\n        + [`0+` **Request** sections](#def-request-section)\n            + [`0-1` **Headers** section](#def-headers-section)\n            + [`0-1` **Attributes** section](#def-attributes-section)\n            + [`0-1` **Body** section](#def-body-section)\n            + [`0-1` **Schema** section](#def-schema-section)\n        + [`1+` **Response** sections](#def-response-section)\n            + [`0-1` **Headers** section](#def-headers-section)\n            + [`0-1` **Attributes** section](#def-attributes-section)\n            + [`0-1` **Body** section](#def-body-section)\n            + [`0-1` **Schema** section](#def-schema-section)\n+ [`0+` **Resource Group** sections](#def-resourcegroup-section)\n    + [`0+` **Resource** sections](#def-resource-section) (see above)\n+ [`0+` **Data Structures** section](#def-data-structures)\n\n> **NOTE:** The number prior to a section name denotes the allowed number of\n> the section occurrences.\n\n> **NOTE:** Refer to [Sections Reference](#def-sections-reference) for\n> description of a specific section type.\n\n<a name=\"def-blueprint-section\"></a>\n## Blueprint section\nA _Section_ represents a logical unit of an API Blueprint. For example: an API\noverview, a group of resources or a resource definition.\n\nIn general a section is **defined** using a **keyword** in a Markdown entity.\nDepending on the type of section the keyword is written either as a Markdown\nheader entity or in a list item entity.\n\nA section definition **may** also contain additional variable components such\nas its **identifier** and additional modifiers.\n\n> **NOTE**: There are two special sections that are recognized by their\n> position in the document instead of a keyword: The [Metadata section](#def-metadata-section) and\n> the [API Name & Overview section](#def-api-name-section). Refer to the respective section entry\n> for details on its definition.\n\n#### Example: Header-defined sections\n\n    # <keyword>\n\n     ...\n\n    # <keyword>\n\n     ...\n\n\n> **NOTE:** While this specification uses \"atx\"-style headers (using `#`s)\n>  you can also use \"Setext\" [header syntax][] interchangeably:\n>\n>     <keyword>\n>     =========\n>\n>     ...\n>\n>     <keyword>\n>     =========\n>\n>     ...\n\n#### Example: List-defined sections\n\n    + <keyword>\n\n     ...\n\n    + <keyword>\n\n     ...\n\n> **NOTE:**  While this specification uses pluses (`+`) as list markers you can\n> use any Markdown [list syntax][] using asterisks (`*`), pluses (`+`) and\n> hyphens (`-`) interchangeably:\n>\n>     * <keyword>\n>\n>     ...\n>\n>     - <keyword>\n>\n>     ...\n\n<a name=\"def-section-types\"></a>\n### Section types\nThere are several types of API Blueprint sections. You can find the complete\nlisting of the section types in the\n[Section Reference](#def-sections-reference).\n\n**The Blueprint section chapter discusses the section syntax in general.**\n**A specific section type may conform only to some parts of this general syntax.**\nAlways refer for respective section reference for details on its syntax.\n\n<a name=\"def-section-structure\"></a>\n### Section structure\nA general structure of an API Blueprint section defined by a **keyword**\nincludes an **identifier** (name), section **description** and **nested\nsections** or a specifically formatted content.\n\n#### Example: Header-defined section structure\n\n    # <keyword> <identifier>\n\n    <description>\n\n    <specific content>\n\n    <nested sections>\n\n#### Example: List-defined section structure\n\n    + <keyword> <identifier>\n\n        <description>\n\n        <specific content>\n\n        <nested sections>\n\n<a name=\"def-keywords\"></a>\n### Keywords\nFollowing reserved keywords are used in section definitions:\n\n#### Header keywords\n- `Group`\n- `Data Structures`\n- [HTTP methods][httpmethods] (e.g. `GET, POST, PUT, DELETE`...)\n- [URI templates][uritemplate] (e.g. `/resource/{id}`)\n- Combinations of an HTTP method and URI Template (e.g. `GET /resource/{id}`)\n\n#### List keywords\n- `Request`\n- `Response`\n- `Body`\n- `Schema`\n- `Model`\n- `Header` & `Headers`\n- `Parameter` & `Parameters`\n- `Values`\n- `Attribute` & `Attributes`\n- `Relation`\n\n> **NOTE: Avoid using these keywords in other Markdown headers or lists**\n\n> **NOTE:** With the exception of HTTP methods keywords the section keywords\n> are case insensitive.\n\n<a name=\"def-identifier\"></a>\n### Identifier\nA section definition **may** or **must** include an identifier of the section.\nAn **identifier is any non-empty combination of any character except `[`, `]`,\n`(`, `)` and newline characters**.\n\nAn identifier **must not** contain any of the [keywords](#def-keywords).\n\n#### Example\n\n```\nAdam's Message 42\n```\n\n```\nmy-awesome-message_2\n```\n\n\n<a name=\"def-description\"></a>\n### Description\nA section description is any arbitrary Markdown-formatted content following the\nsection definition.\n\nIt is possible to use any Markdown header or list item in a section description\nas long as it does not clash with any of the\n[reserved keywords](#def-keywords).\n\n> **NOTE:** It is considered good practice to keep the header level nested\n> under the actual section.\n\n<a name=\"def-nested-sections\"></a>\n### Nested sections\nA section **may** contain another nested section(s).\n\nDepending on the nested section type, to nest a section simply increase its\nheader level or its list item indentation. Anything between the section start\nand the start of following section at the same level is considered to be part\nof the section.\n\nWhich sections can be nested and where depends upon the section in case, as\ndescribed in the relevant section's entry.\n\n#### Example: Nested header-defined section\n\n    # <section definition>\n\n     ...\n\n    ## <nested section definition>\n\n     ...\n\n#### Example: Nested list-defined section\n\n    + <section definition>\n\n         ...\n\n        + <nested section definition>\n\n         ...\n\n> **NOTE:** While not necessary it is a good habit to increase the level of a\n> nested section markdown-header.\n\n> **NOTE:** A markdown-list section is always considered to be nested under the\n> preceding markdown-header section.\n\n---\n\n<a name=\"def-sections-reference\"></a>\n# II. Sections Reference\n> **NOTE:** Sections marked as \"Abstract\" serve as a base for other sections\n> and as such they **cannot** be used directly.\n\n\n# Abstract\n\n<a name=\"def-named-section\"></a>\n## Named section\n- **Abstract**\n- **Parent sections:** vary, see descendants\n- **Nested sections:** vary, see descendants\n- **Markdown entity:** header, list\n- **Inherits from**: none\n\n#### Definition\nDefined by a [keyword](#def-keywords) followed by an optional section name -\n[identifier](#def-identifier) in a Markdown header or list entity.\n\n```\n# <keyword> <identifier>\n```\n\n```\n+ <keyword> <identifier>\n```\n\n#### Description\nNamed section is the base section for most of the API Blueprint sections. It\nconforms to the [general section](#def-section-structure) and as such it is\ncomposed of a section name (identifier), description and nested sections or\nspecific formatted content (see descendants descriptions).\n\n#### Example\n\n    # <keyword> Section Name\n    This the `Section Name` description.\n\n    - one\n    - **two**\n    - three\n\n    <nested sections> |  <formatted content>\n\n---\n\n<a name=\"def-asset-section\"></a>\n## Asset section\n- **Abstract**\n- **Parent sections:** vary, see descendants\n- **Nested sections:** none\n- **Markdown entity:** list\n- **Inherits from**: none\n\n#### Definition\nDefined by a [keyword](#def-keywords) in Markdown list entity.\n\n    + <keyword>\n\n#### Description\nThe asset section is the base section for atomic data in API Blueprint. The content\nof this section is expected to be a\n[pre-formatted code block](http://daringfireball.net/projects/markdown/syntax#precode).\n\n#### Example\n\n    + <keyword>\n\n            {\n                \"message\": \"Hello\"\n            }\n\n#### Example: Fenced code blocks\n\n    + <keyword>\n\n        ```\n        {\n            \"message\": \"Hello\"\n        }\n        ```\n\n---\n\n<a name=\"def-payload-section\"></a>\n## Payload section\n- **Abstract**\n- **Parent sections:** vary, see descendants\n- **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)\n- **Markdown entity:** list\n- **Inherits from**: [Named section](#def-named-section)\n\n#### Definition\nDefined by a [keyword](#def-keywords) in Markdown list entity. The keyword **may** be followed by identifier.\nThe definition **may** include payload's media-type enclosed in braces.\n\n    + <keyword> <identifier> (<media type>)\n\n> **NOTE:** Refer to descendant for the particular section type definition.\n\n#### Description\nPayload sections represent the information transferred as a payload of an HTTP\nrequest or response messages. A Payload consists of optional meta information\nin the form of HTTP headers and optional content in the form of an HTTP body.\n\nFurthermore, in API Blueprint context, a payload includes its description,\ndescription of its message-body attributes and a message-body validation\nschema.\n\nA payload **may** have its media type associated. A payload's media type\nrepresents the metadata received or sent in the form of a HTTP `Content-Type`\nheader. When specified a payload **should** include nested\n[Body section](#def-body-section).\n\nThis section **should** include at least one of the following nested sections:\n\n- [`0-1` Headers section](#def-headers-section)\n- [`0-1` Attributes section](#def-attributes-section)\n- [`0-1` Body section](#def-body-section)\n- [`0-1` Schema section](#def-schema-section)\n\nIf there is no nested section the content of the payload section is considered\nas content of the [Body section](#def-body-section).\n\n#### Relation of Body, Schema and Attributes sections\nEach of body, schema and attributes sections describe a message payload's body.\nThese descriptions **should** be consistent, not violating each other. When\nmultiple body descriptions are provided they **should** be prioritized as\nfollows:\n\n1. For resolving message-body schema\n    1. Schema section\n    2. Attributes section\n    3. Body section\n\n2. For resolving message-body example\n    1. Body section\n    2. Attributes section\n    3. Schema section\n\n#### Referencing\nInstead of providing a payload section content, a\n[model payload section](#def-model-section) can be referenced using the\nMarkdown implicit [reference syntax][]:\n\n    [<identifier>][]\n\n#### Example\n\n    + <keyword> Payload Name (application/json)\n\n        This the `Payload Name` description.\n\n        + Headers\n\n         ...\n\n        + Body\n\n         ...\n\n        + Schema\n\n        ...\n\n#### Example: Referencing model payload\n\n    + <keyword> Payload Name\n\n        [Resource model identifier][]\n\n---\n\n\n# Section Basics\n\n\n<a name=\"def-metadata-section\"></a>\n## Metadata section\n- **Parent sections:** none\n- **Nested sections:** none\n- **Markdown entity:** special\n- **Inherits from**: none\n\n#### Definition\nKey-value pairs. Each key is separated from its value by a colon (`:`). One\npair per line. Starts at the beginning of the document and ends with the first\nMarkdown element that is not recognized as a key-value pair.\n\n#### Description\nMetadata keys and their values are tool-specific. Refer to relevant tool\ndocumentation for the list of supported keys.\n\n#### Example\n\n    FORMAT: 1A\n    HOST: http://blog.acme.com\n\n---\n\n<a name=\"def-api-name-section\"></a>\n## API name & overview section\n- **Parent sections:** none\n- **Nested sections:** none\n- **Markdown entity:** special, header\n- **Inherits from**: [Named section](#def-named-section)\n\n#### Definition\nDefined by the **first** Markdown header in the blueprint document, unless it\nrepresents another section definition.\n\n#### Description\nName and description of the API\n\n#### Example\n\n    # Basic ACME Blog API\n    Welcome to the **ACME Blog** API. This API provides access to the **ACME\n    Blog** service.\n\n---\n\n<a name=\"def-resourcegroup-section\"></a>\n## Resource group section\n- **Parent sections:** none\n- **Nested sections:** [`0+` Resource section](#def-resource-section)\n- **Markdown entity:** header\n- **Inherits from**: [Named section](#def-named-section)\n\n#### Definition\nDefined by the `Group` keyword followed by group [name (identifier)](#def-identifier):\n\n    # Group <identifier>\n\n#### Description\nThis section represents a group of resources (Resource Sections). **May**\ninclude one or more nested [Resource Sections](#def-resource-section).\n\n#### Example\n\n```apib\n# Group Blog Posts\n\n## Resource 1 [/resource1]\n\n ...\n\n# Group Authors\nResources in this groups are related to **ACME Blog** authors.\n\n## Resource 2 [/resource2]\n\n ...\n```\n\n---\n\n<a name=\"def-resource-section\"></a>\n## Resource section\n- **Parent sections:** none, [Resource group section](#def-resourcegroup-section)\n- **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)\n- **Markdown entity:** header\n- **Inherits from**: [Named section](#def-named-section)\n\n#### Definition\nDefined by an [URI template][uritemplate]:\n\n    # <URI template>\n\n**-- or --**\n\nDefined by a resource [name (identifier)](#def-identifier) followed by an\n[URI template][uritemplate] enclosed in square brackets `[]`.\n\n    # <identifier> [<URI template>]\n\n**-- or --**\n\nDefined by an [HTTP request method][httpmethods] followed by [URI template][uritemplate]:\n\n    # <HTTP request method> <URI template>\n\n**-- or --**\n\nDefined by a resource [name (identifier)](#def-identifier) followed by an\n[HTTP request method][httpmethods] and an [URI template][uritemplate] enclosed\nin square brackets `[]`:\n\n    # <identifier> [<HTTP request method> <URI template>]\n\n> **NOTE:** In the latter two cases the rest of this section represents the\n> [Action section](#def-action-section) including its description and nested\n> sections and **follows the rules of the Action section instead**.\n\n#### Description\nAn API [resource](http://www.w3.org/TR/di-gloss/#def-resource) as specified by\nits *URI* or a set of resources (a resource template) matching its *URI\ntemplate*.\n\nThis section **should** include at least one nested\n[Action section](#def-action-section) and **may** include following nested\nsections:\n\n- [`0-1` URI parameters section](#def-uriparameters-section)\n\n    URI parameters defined in the scope of a Resource section apply to\n    _any and all_ nested Action sections except when an [URI template][uritemplate] has\n    been defined for the Action.\n\n- [`0-1` Attributes section][]\n\n    Attributes defined in the scope of a Resource section represent Resource\n    attributes. If the resource is defined with a name these attributes **may**\n    be referenced in [Attributes sections][].\n\n- [`0-1` Model section](#def-model-section)\n\n- Additional [Action sections](#def-action-section)\n\n> **NOTE:** A blueprint document may contain multiple sections for the same\n> resource (or resource set), as long as their HTTP methods differ. However it\n> is considered good practice to group multiple HTTP methods under one resource\n> (resource set).\n\n#### Example\n\n```apib\n# Blog Posts [/posts/{id}]\nResource representing **ACME Blog** posts.\n```\n\n```apib\n# /posts/{id}\n```\n\n```apib\n# GET /posts/{id}\n```\n\n---\n\n<a name=\"def-model-section\"></a>\n## Resource model section\n- **Parent sections:** [Resource section](#def-resource-section)\n- **Nested sections:** [Refer to payload section](#def-payload-section)\n- **Markdown entity:** list\n- **Inherits from**: [Payload section](#def-payload-section)\n\n#### Definition\nDefined by the `Model` keyword followed by an optional media type:\n\n    + Model (<media type>)\n\n#### Description\nA [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) - one\nexemplary representation of the resource in the form of a\n[payload](#def-payload-section).\n\n#### Referencing\nThe payload defined in this section **may** be referenced in any response or\nrequest section in the document using parent section's identifier. You can\nrefer to this payload in any of the following [Request](#def-request-section)\nor [Response](#def-response-section) payload sections using the Markdown\nimplicit [reference syntax][].\n\n#### Example\n\n```apib\n# My Resource [/resource]\n\n+ Model (text/plain)\n\n        Hello World\n\n## Retrieve My Resource [GET]\n\n+ Response 200\n\n    [My Resource][]\n```\n\n---\n\n<a name=\"def-schema-section\"></a>\n## Schema section\n- **Parent sections:** [Payload section](#def-payload-section)\n- **Nested sections:** none\n- **Markdown entity:** list\n- **Inherits from**: [Asset section](#def-asset-section)\n\n#### Definition\nDefined by the `Schema` keyword in Markdown list entity.\n\n    + Schema\n\n#### Description\nSpecifies a validation schema for the HTTP message-body of parent payload section.\n\n#### Example\n\nFollowing 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.\n\n```apib\n## Retrieve a Message [GET]\n\n+ Response 200 (application/json)\n    + Body\n\n            {\"message\": \"Hello world!\"}\n\n    + Schema\n\n            {\n                \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n                \"type\": \"object\",\n                \"properties\": {\n                    \"message\": {\n                        \"type\": \"string\"\n                    }\n                }\n            }\n```\n\n---\n\n<a name=\"def-action-section\"></a>\n## Action section\n- **Parent sections:** [Resource section](#def-resource-section)\n- **Nested sections:**\n    [`0-1` Relation section](#def-relation-section),\n    [`0-1` URI parameters section](#def-uriparameters-section),\n    [`0-1` Attributes section](#def-attributes-section),\n    [`0+` Request section](#def-request-section),\n    [`1+` Response section](#def-response-section)\n- **Markdown entity:** header\n- **Inherits from**: [Named section](#def-named-section)\n\n#### Definition\nDefined by an [HTTP request method][httpmethods]:\n\n    ## <HTTP request method>\n\n**-- or --**\n\nDefined by an action [name (identifier)](#def-identifier) followed by an\n[HTTP request method][httpmethods] enclosed in square brackets `[]`.\n\n    ## <identifier> [<HTTP request method>]\n\n**-- or --**\n\nDefined by an action [name (identifier)](#def-identifier) followed by an\n[HTTP request method][httpmethods] and\n[URI template][uritemplate] enclosed in square brackets `[]`.\n\n    ## <identifier> [<HTTP request method> <URI template>]\n\n#### Description\nDefinition of at least one complete HTTP transaction as performed with the\nparent resource section. An action section **may** consist of multiple HTTP\ntransaction examples for the given HTTP request method.\n\nThis section **may** include one nested\n[URI parameters section](#def-uriparameters-section) describing any URI\nparameters _specific_ to the action – URI parameters discussed in the scope of\nan Action section apply to the respective Action section ONLY.\n\nThis section **may** include one nested [Attributes section][] defining the\ninput (request) attributes of the section. If present, these attributes\n**should** be inherited in every Action's [Request section][] unless specified\notherwise.\n\nAction section **should** include at least one nested\n[Response section](#def-response-section) and **may** include additional nested\n[Request](#def-request-section) and [Response](#def-response-section) sections.\n\nNested Request and Response sections **may** be ordered into groups where each\ngroup represents one transaction example. The first transaction example group\nstarts with the first nested Request or Response section. Subsequent groups\nstart with the first nested Request section following a Response section.\n\nMultiple Request and Response nested sections within one transaction example\n**should** have different identifiers.\n\n#### Example\n\n```apib\n# Blog Posts [/posts{?limit}]\n ...\n\n## Retrieve Blog Posts [GET]\nRetrieves the list of **ACME Blog** posts.\n\n+ Parameters\n    + limit (optional, number) ... Maximum number of posts to retrieve\n\n+ Response 200\n\n        ...\n\n## Create a Post [POST]\n\n+ Attributes\n\n        ...\n\n+ Request\n\n        ...\n\n+ Response 201\n\n        ...\n\n## Delete a Post [DELETE /posts/{id}]\n\n+ Parameters\n    + id (string) ... Id of the post\n\n+ Response 204\n```\n\n#### Example Multiple Transaction Examples\n\n```apib\n# Resource [/resource]\n## Create Resource [POST]\n\n+ request A\n\n        ...\n\n+ response 200\n\n        ...\n\n+ request B\n\n        ...\n\n+ response 200\n\n        ...\n\n+ response 500\n\n        ...\n\n+ request C\n\n        ...\n\n+ request D\n\n        ...\n\n+ response 200\n\n        ...\n```\n\n> **NOTE:** The \"Multiple Transaction Examples\" example demonstrates three\n> transaction examples for one given action:\n>\n> 1. 1st example: request `A`, response `200`\n> 2. 2nd example: request `B`, responses `200` and `500`\n> 3. 3rd example: requests `C` and `D`, response `200`\n\n---\n\n<a name=\"def-request-section\"></a>\n## Request section\n- **Parent sections:** [Action section](#def-action-section)\n- **Nested sections:** [Refer to payload section](#def-payload-section)\n- **Markdown entity:** list\n- **Inherits from**: [Payload section](#def-payload-section)\n\n#### Definition\nDefined by the `Request` keyword followed by an optional [identifier](#def-identifier):\n\n    + Request <identifier> (<Media Type>)\n\n#### Description\nOne HTTP request-message example – payload.\n\n#### Example\n\n```apib\n+ Request Create Blog Post (application/json)\n\n        { \"message\" : \"Hello World.\" }\n```\n\n---\n\n<a name=\"def-response-section\"></a>\n## Response section\n- **Parent sections:** [Action section](#def-action-section)\n- **Nested sections:** [Refer to payload section](#def-payload-section)\n- **Markdown entity:** list\n- **Inherits from**: [Payload section](#def-payload-section)\n\n#### Definition\nDefined by the `Response` keyword. The response section definition **should**\ninclude an [HTTP status code][] as its identifier.\n\n    + Response <HTTP status code> (<Media Type>)\n\n#### Description\nOne HTTP response-message example – payload.\n\n#### Example\n\n```apib\n+ Response 201 (application/json)\n\n            { \"message\" : \"created\" }\n```\n\n---\n\n<a name=\"def-uriparameters-section\"></a>\n## URI parameters section\n- **Parent Sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section)\n- **Nested Sections:** none\n- **Markdown entity:** list\n- **Inherits from**: none, special\n\n#### Definition\nDefined by the `Parameters` keyword written in a Markdown list item:\n\n    + Parameters\n\n#### Description\nDiscussion of URI parameters _in the scope of the parent section_.\n\nThis section **must** be composed of nested list items only. This section\n**must not** contain any other elements. Each list item describes a single URI\nparameter. The nested list items subsections inherit from the\n[Named section](#def-named-section) and are subject to additional formatting as\nfollows:\n\n    + <parameter name>: `<example value>` (<type> | enum[<type>], required | optional) - <description>\n\n        <additional description>\n\n        + Default: `<default value>`\n\n        + Members\n            + `<enumeration value 1>`\n            + `<enumeration value 2>`\n            ...\n            + `<enumeration value N>`\n\nWhere:\n\n+ `<parameter name>` is the parameter name as written in\n  [Resource Section](#def-resource-section)'s URI (e.g. \"id\").\n+ `<description>` is any **optional** Markdown-formatted description of the\n  parameter.\n+ `<additional description>` is any additional **optional** Markdown-formatted\n  [description](#def-description) of the parameter.\n+ `<default value>` is an **optional** default value of the parameter – a value\n  that is used when no value is explicitly set (optional parameters only).\n+ `<example value>` is an **optional** example value of the parameter (e.g. `1234`).\n+ `<type>` is the **optional** parameter type as expected by the API (e.g.\n  \"number\", \"string\", \"boolean\"). \"string\" is the **default**.\n+ `Members` is the **optional** enumeration of possible values.\n  `<type>` should be surrounded by `enum[]` if this is present.\n  For example, if enumeration values are present for a parameter whose type is\n  `number`, then `enum[number]` should be used instead of `number` to.\n+ `<enumeration value n>` represents an element of enumeration type.\n+ `required` is the **optional** specifier of a required parameter\n  (this is the **default**)\n+ `optional` is the **optional** specifier of an optional parameter.\n\n> **NOTE:** This section **should only** contain parameters that are specified\n> in the parent's resource URI template, and does not have to list every URI\n> parameter.\n\n#### Example\n\n```apib\n# GET /posts/{id}\n```\n\n```apib\n+ Parameters\n    + id - Id of a post.\n```\n\n```apib\n+ Parameters\n    + id (number) - Id of a post.\n```\n\n```apib\n+ Parameters\n    + id: `1001` (number, required) - Id of a post.\n```\n\n```apib\n+ Parameters\n    + id: `1001` (number, optional) - Id of a post.\n        + Default: `20`\n```\n\n```apib\n+ Parameters\n    + id (enum[string])\n\n        Id of a Post\n\n        + Members\n            + `A`\n            + `B`\n            + `C`\n```\n---\n\n<a name=\"def-attributes-section\"></a>\n## Attributes Section\n- **Parent sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section) | [Payload section](#def-payload-section)\n- **Nested sections:** See **[Markdown Syntax for Object Notation][MSON]**\n- **Markdown entity:** list\n- **Inherits from**: none\n\n#### Definition\nDefined by the `Attributes` keyword followed by an optional\n[MSON Type Definition][] enclosed in parentheses.\n\n    + Attributes <Type Definition>\n\n`<Type Definition>` is the type definition of the data structure being\ndescribed. If the `<Type Definition>` is not specified, an `object` base type\nis assumed. See [MSON Type Definition][] for details.\n\n##### Example\n\n```apib\n+ Attributes (object)\n```\n\n#### Description\nThis section describes a data structure using the\n**[Markdown Syntax for Object Notation][MSON] (MSON)**.\nBased on the parent section, the data structure being described is one of the\nfollowing:\n\n1. Resource data structure attributes ([Resource section](#def-resource-section))\n2. Action request attributes ([Action section](#def-action-section))\n3. Payload message-body attributes ([Payload section](#def-payload-section))\n\nData structures defined in this section **may** refer to any arbitrary data\nstructures defined in the [Data Structures section](#def-data-structures) as\nwell as to any data structures defined by a named resource attributes\ndescription (see below).\n\n#### Resource Attributes description\nDescription of the resource data structure.\n\nIf defined in a named [Resource section](#def-resource-section), this data\nstructure **may** be referenced by other data structures using the resource\nname.\n\n##### Example\n\n```apib\n# Blog Post [/posts/{id}]\nResource representing **ACME Blog** posts.\n\n+ Attributes\n    + id (number)\n    + message (string) - The blog post article\n    + author: john@appleseed.com (string) - Author of the blog post\n```\n\n> **NOTE:** This data structure can be later referred as:\n>\n>     + Attributes (Blog Post)\n>\n\n#### Action Attributes description\nDescription of the default request message-body data structure.\n\nIf defined, all the [Request sections](#def-request-section) of the respective\n[Action section](#def-action-section) inherits these attributes unless\nspecified otherwise.\n\n##### Example\n\n```apib\n## Create a Post [POST]\n\n+ Attributes\n    + message (string) - The blog post article\n    + author: john@appleseed.com (string) - Author of the blog post\n\n+ Request (application/json)\n\n+ Request (application/yaml)\n\n+ Response 201\n```\n\n#### Payload Attributes description\nDescription of payload (request, response, model) message-body attributes.\n\nNot every attribute has to be described. However, when an attribute is\ndescribed, it **should** appear in the respective\n[Body section](#def-body-section) example, if a Body section is provided.\n\nIf defined, the [Body section](#def-body-section) **may** be omitted and the\nexample representation **should** be generated from the attributes description.\n\nThe description of message-body attributes **may** be used to describe\nmessage-body validation if no [Schema section](#def-schema-section) is\nprovided. When a Schema section is provided, the attributes description\n**should** conform to the schema.\n\n##### Example\n\n```apib\n## Retrieve a Post [GET]\n\n+ Response 200 (application/json)\n\n    + Attributes (object)\n        + message (string) - Message to the world\n\n    + Body\n\n            { \"message\" : \"Hello World.\" }\n```\n\n---\n\n<a name=\"def-headers-section\"></a>\n## Headers section\n- **Parent sections:** [Payload section](#def-payload-section)\n- **Nested sections:** none\n- **Markdown entity:** list\n- **Inherits from**: none\n\n#### Definition\nDefined by the `Headers` keyword in Markdown list entity.\n\n    + Headers\n\n#### Description\nSpecifies the HTTP message-headers of the parent payload section. The content\nthis section is expected to be a [pre-formatted code block](http://daringfireball.net/projects/markdown/syntax#precode)\nwith the following syntax:\n\n    <HTTP header name>: <value>\n\nOne HTTP header per line.\n\n#### Example\n\n```apib\n+ Headers\n\n        Accept-Charset: utf-8\n        Connection: keep-alive\n        Content-Type: multipart/form-data, boundary=AaB03x\n```\n\n---\n\n<a name=\"def-body-section\"></a>\n## Body section\n- **Parent sections:** [Payload section](#def-payload-section)\n- **Nested sections:** none\n- **Markdown entity:** list\n- **Inherits from**: [Asset section](#def-asset-section)\n\n#### Definition\nDefined by the `Body` keyword in Markdown list entity.\n\n    + Body\n\n#### Description\nSpecifies the HTTP message-body of a payload section.\n\n#### Example\n\n```apib\n+ Body\n\n        {\n            \"message\": \"Hello\"\n        }\n```\n\n---\n\n\n<a name=\"def-data-structures\"></a>\n## Data Structures section\n- **Parent sections:** none\n- **Nested sections:** _MSON Named Type definition_ (see below)\n- **Markdown entity:** header\n- **Inherits from**: none\n\n#### Definition\nDefined by the `Data Structures` keyword.\n\n    # Data Structures\n\n#### Description\nThis section holds arbitrary data structures definitions defined in the form of\n[MSON Named Types][].\n\nData structures defined in this section **may** be used in any [Attributes section][].\nSimilarly, any data structures defined in a [Attributes section][] of a named\n[Resource Section][] **may** be used in a data structure definition.\n\nRefer to the [MSON][] specification for full details on how to define an MSON Named type.\n\n#### Example\n\n```apib\n# Data Structures\n\n## Message (object)\n\n+ text (string) - text of the message\n+ author (Author) - author of the message\n\n## Author (object)\n\n+ name: John\n+ email: john@appleseed.com\n```\n\n#### Example reusing Data Structure in Resource\n\n```apib\n# User [/user]\n\n+ Attributes (Author)\n\n# Data Structures\n\n## Author (object)\n\n+ name: John\n+ email: john@appleseed.com\n```\n\n#### Example reusing Resource-defined Data Structure\n\n```apib\n# User [/user]\n\n+ Attributes\n    + name: John\n    + email: john@appleseed.com\n\n# Data Structures\n\n## Author (User)\n```\n\n---\n\n<a name=\"def-relation-section\"></a>\n## Relation section\n- **Parent sections:** [Action section](#def-action-section)\n- **Nested Sections:** none\n- **Markdown entity:** list\n- **Inherits from**: none\n\n#### Definition\nDefined by the `Relation` keyword written in a Markdown list item followed by a\ncolon (`:`) and a link relation identifier.\n\n    + Relation: <link relation identifier>\n\n#### Description\nThis section specifies a [link relation type](https://tools.ietf.org/html/rfc5988#section-4)\nfor the given action as specified by [RFC 5988](https://tools.ietf.org/html/rfc5988).\n\n> **NOTE:** The link relation identifiers should be unique per resource in the blueprint document.\n\n#### Example\n\n```apib\n# Task [/tasks/{id}]\n\n+ Parameters\n    + id\n\n## Retrieve Task [GET]\n\n+ Relation: task\n+ Response 200\n\n        { ... }\n\n## Delete Task [DELETE]\n\n+ Relation: delete\n+ Response 204\n```\n\n---\n\n\n<br>\n\n<a name=\"def-appendix\"></a>\n# III. Appendix\n\n<a name=\"def-uri-templates\"></a>\n## URI Templates\n\nThe API Blueprint uses a subset of [RFC6570][rfc6570] to define a resource URI Template.\n\n### URI Path Segment\n\nAt its simplest form – without any variables – a path segment of an\nURI Template is identical to an URI path segment:\n\n```\n/path/to/resources/42\n```\n\n### URI Template Variable\n\nVariable names are case-sensitive. The variable name may consists of following\ncharacters **only**:\n\n- ASCII alpha numeric characters (`a-z`, `A-Z`)\n- Decimal digits (`0-9`)\n- `_`\n- [Percent-encoded][pct-encoded] characters\n- `.`\n\nMultiple variables are separated by the comma **without** any leading or\ntrailing spaces. A variable(s) **must** be enclosed in braces – `{}`\n**without** any additional leading or trailing whitespace.\n\n#### Operators\n\nThe first variable in the braces **might** be preceded by an operator.\nAPI Blueprint currently supports the following operators:\n\n- `#` – _fragment identifier_ operator\n- `+` – _reserved value_ operator\n- `?` – _form-style query_ operator\n- `&` – _form-style query continuation_ operator\n\n#### Examples\n\n```\n{var}\n{var1,var2,var3}\n{#var}\n{+var}\n{?var}\n{?var1,var2}\n{?%24var}\n{&var}\n```\n\n> **NOTE:** The [explode variable modifier][uri-explode] is also supported.\n> Refer to RFC6570 for its description.\n\n#### Variable Reserved Values\n\nFollowing characters are **reserved** in variable _values_:\n\n`:` / `/` / `?` / `#` / `[` / `]` / `@` / `!` / `$` / `&` / `'` / `(` / `)` / `*` / `+` / `,` / `;` / `=`\n\n### Path Segment Variable\n\nSimple path segment component variable is defined without any operator:\n\n```\n/path/to/resources/{var}\n```\n\nWith `var := 42` the expansion is `/path/to/resources/42`.\n\n> **NOTE:** RFC6570 – Level 1\n\n### Fragment Identifier Variable\n\nURI Template variables for fragment identifiers are defined using the\ncrosshatch (`#`) operator:\n\n```\n/path/to/resources/42{#var}\n```\n\nWith `var := my_id` the expansion is `/path/to/resources/42#my_id`.\n\n> **NOTE:** RFC6570 – Level 2\n\n### Variable with Reserved Characters Values\n\nTo define URI Template variables with reserved URI characters,\nuse the plus (`+`) operator:\n\n```\n/path/{+var}/42\n```\n\nWith `var := to/resources` the expansion is `/path/to/resources/42`.\n\n> **NOTE:** RFC6570 – Level 2\n\n### Form-style Query Variable\n\nTo define variables for a form-style query use the question mark (`?`) operator\n\n```\n/path/to/resources/{varone}{?vartwo}\n```\n\nWith `varone := 42` and `vartwo = hello` the expansion is `/path/to/resources/42?vartwo=hello`.\n\nTo continue a form-style query use the ampersand (`&`) operator:\n\n```\n/path/to/resources/{varone}?path=test{&vartwo,varthree}\n```\n\nWith `varone := 42`, `vartwo = hello`, `varthree = 1024` the expansion is `/path/to/resources/42?path=test&vartwo=hello&varthree=1024`.\n\n> **NOTE:** RFC6570 – Part of Level 3\n\n---\n\n[apiblueprint.org]: http://apiblueprint.org\n[markdown syntax]: http://daringfireball.net/projects/markdown\n[reference syntax]: http://daringfireball.net/projects/markdown/syntax#link\n[gitHub flavored markdown syntax]: https://help.github.com/articles/github-flavored-markdown\n[httpmethods]: https://github.com/for-GET/know-your-http-well/blob/master/methods.md#know-your-http-methods-well\n[uritemplate]: #def-uri-templates\n[rfc6570]: http://tools.ietf.org/html/rfc6570\n[HTTP status code]: https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md\n[header syntax]: https://daringfireball.net/projects/markdown/syntax#header\n[list syntax]: https://daringfireball.net/projects/markdown/syntax#list\n[pct-encoded]: http://en.wikipedia.org/wiki/Percent-encoding\n[uri-explode]: http://tools.ietf.org/html/rfc6570#section-2.4.2\n[examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples\n\n[MSON]: https://github.com/apiaryio/mson\n[MSON Named Types]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#22-named-types\n[MSON Type Definition]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#35-type-definition\n\n[`0-1` Attributes section]: #def-attributes-section\n[Attributes section]: #def-attributes-section\n[Attributes sections]: #def-attributes-section\n\n[Resource Section]: #def-resource-section\n\n[Request section]: #def-request-section\n"
  },
  {
    "path": "Advanced Tutorial.md",
    "content": "# Advanced API Blueprint Tutorial\n\nWelcome to the advanced API Blueprint tutorial! This tutorial will take you\nthrough advanced topics like JSON Schema, request and response attributes, data\nstructures and relation types.\n\nThis tutorial assumes that you have read the [API Blueprint Tutorial](https://github.com/apiaryio/api-blueprint/blob/master/Tutorial.md).\n\n## JSON Schema\n\nAction request and response bodies can have associated schemas that describe\nthe allowed structure of the body content. JSON bodies are typically described\nwith [JSON Schema](http://json-schema.org/). Given a simple JSON response body\nwe can describe the structure of the response with JSON Schema in a `+ Schema`\nsection.\n\nThe schema can describe the type of each member, which members are required,\ndefault values, and support a number of other advanced features. Below is an\nexample, taken from the \n[Polls API](https://raw.github.com/apiaryio/api-blueprint/master/examples/Polls%20API.md)\nblueprint:\n\n```apib\n### Create a New Question [POST]\nYou may create your own question using this action. It takes a JSON object\ncontaining a question and a collection of answers in the form of choices.\n\n+ Request (application/json)\n\n    + Body\n\n            {\n              \"question\": \"Favourite language?\"\n              \"choices\": [\n                \"Swift\",\n                \"Objective-C\"\n              ]\n            }\n\n    + Schema\n\n            {\n              \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n              \"type\": \"object\",\n              \"properties\": {\n                \"question\": {\n                  \"type\": \"string\"\n                },\n                \"choices\": {\n                  \"type\": \"array\",\n                  \"items\": {\n                    \"type\": \"string\"\n                  },\n                  \"minItems\": 2\n                }\n              }\n            }\n```\n\n## Attributes\n\nAnother way of describing examples and the structure of your request and\nresponse content is by using [MSON](https://github.com/apiaryio/mson#readme).\nMSON, like API Blueprint, allows you to use human-readable plain text to\ndescribe things rather than formats designed for computer parsing like JSON or\nYAML. Where API Blueprint allows you to describe your API, MSON allows you to\ndescribe data structures.\n\nMSON can be added to resources, actions, and individual requests or responses\nvia an `+ Attributes` section.\n\nCreating a new question in the polls API can be modeled using MSON:\n\n```apib\n### Create a New Question [POST]\nYou may create your own question using this action. It takes a JSON object\ncontaining a question and a collection of answers in the form of choices.\n\n+ Request (application/json)\n\n    + Attributes\n\n        + question: Favourite Language? (required)\n        + choices: Swift, `Objective-C` (array, required)\n\n```\n\nWhen the above blueprint is parsed it will have a JSON body and JSON Schema\nexample generated for it from the MSON attributes. Note, however, that the\ngenerated JSON Schema may differ from a hand-written one. In this example, the\n`minItems` will not be set. If you have such constraints you can override the\ngenerated schema by providing your own, in which case only the JSON body will\nbe generated.\n\n## Data Structures\n\nOnce you start using MSON, you may find yourself wanting to reuse certain\ncommonly used or nested data structure components. This is possible with the\n`## Data Structures` section. Attributes sections can then reference the data\nstructures defined in the Data Structures or other resource sections by name.\n\nFor example, using the polls API question collection resource, we can split out\nthe `Question` and `Choice` objects:\n\n```apib\n### List All Questions [GET]\n+ Response 200 (application/json)\n\n    + Attributes (array[Question])\n\n## Data Structures\n\n### Question\n+ question: Favourite programming language? (required)\n+ published_at: `2014-11-11T08:40:51.620Z` (required)\n+ url: /questions/1 (required)\n+ choices (array[Choice], required)\n\n### Choice\n+ choice: Javascript (required)\n+ url: /questions/1/choices/1 (required)\n+ votes: 2048 (number, required)\n\n```\n\n## Relation Types\n\nActions in a blueprint can define a semantic domain-specific meaning by\ndefining a relation type using a `+ Relation` section. This means that an\naction can have a specific meaning regardless of its URI or name, and allows\nclients to be built based on the domain of the API rather than specific URIs.\n\nFor example, in the polls API:\n\n```apib\n## Question [/question/{id}]\n### View a Question Detail [GET]\n+ Relation: self\n\n### Delete a Question [DELETE]\n+ Relation: delete\n\n## Questions Collection [/questions]\n### List All Questions [GET]\n+ Relation: self\n```\n\nA server or client implementation can now use this information to handle the\nspecific API resource and action URIs. Please see the \n[Web Linking RFC 5988](https://tools.ietf.org/html/rfc5988) and the \n[IANA Link Relation Types](http://www.iana.org/assignments/link-relations/link-relations.xhtml) for\nmore information.\n\n## Conclusion\n\nThis tutorial has covered some advanced API Blueprint topics.\nFor more in-depth information and other advanced topics,\nplease see the [API Blueprint Specification](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md).\n"
  },
  {
    "path": "Glossary of Terms.md",
    "content": "# API Blueprint Glossary of Terms\n\nA brief list of terms as used in the [API Blueprint](http://apiblueprint.org) context.\n\n## Glossary\n\n<a name=\"def-action\"></a>\n### Action\nAn **HTTP transaction** (a request-response transaction).\n\nActions are specified by an [HTTP request method](#def-method) within a [resource](#def-resource).\n\n<a name=\"def-api\"></a>\n### API\nAn **HTTP Application programming interface**. Might refer to an API\ndescription. See [**API Blueprint**](#def-api-blueprint).\n\n<a name=\"def-api-blueprint\"></a>\n### API Blueprint\nThe **API Blueprint language**. A format used to describe API in an API blueprint file.\n\n<a name=\"def-asset\"></a>\n### Asset\n**Atomic data**. Most often representing one resource representation in the form of message-body or its validation schema.\n\n<a name=\"def-attribute\"></a>\n### Attribute\nBased on the context, attribute (property) of a message-body data structure, or\nattribute of a resource, or an input attribute of a transition –\n[Action](#def-action).\n\n<a name=\"def-blueprint\"></a>\n### Blueprint\nAn **API description**. A **blueprint file** (or a set of files) that describes an API using the API Blueprint language.\n\n<a name=\"def-data-structure\"></a>\n### Data Structure\nA particular data organization, or a description of it. In API Blueprint, data\nstructures and their [Attributes](#def-attribute) are described using the\nMarkdown Syntax for Object Notation – [MSON][].\n\n<a name=\"def-entity\"></a>\n### Entity\n[**Entity**](http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html) being transferred in a [payload](#def-payload).\n\n<a name=\"def-header\"></a>\n### Header\nA [**message-header**](#def-message-header).\n\n<a name=\"def-method\"></a>\n### Method\nAn [**HTTP Request Method**](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods).\n\n<a name=\"def-message\"></a>\n### Message\nAn **HTTP transaction message**.\n\n<a name=\"def-message-body\"></a>\n### Message body\nAn [**asset**](#def-asset) representing [**HTTP transaction message body**](http://en.wikipedia.org/wiki/HTTP_body_data).\n\n<a name=\"def-message-header\"></a>\n### Message header\nAn [**asset**](#def-asset) representing [**HTTP transaction message header**](http://en.wikipedia.org/wiki/List_of_HTTP_header_fields).\n<a name=\"def-parameter\"></a>\n### Parameter\nAn [**URI template**](#def-uri-template) **variable**.\n\n<a name=\"def-payload\"></a>\n### Payload\nAn **HTTP transaction message** including its **discussion** and any additional [**assets**](#def-asset) such as entity-body validation schema.\n\nA payload may have an **identifier** – a string for a [request](#def-request)\npayload or an \n[HTTP status code](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for a\n[response](#def-response) payload.\n\n<a name=\"def-property\"></a>\n### Property\nAn [entity](#def-entity) field (attribute).\n\n<a name=\"def-request\"></a>\n### Request\nA [**payload**](#def-payload) containing one specific [HTTP Request](http://www.w3.org/TR/di-gloss/#def-http-request).\n\n<a name=\"def-response\"></a>\n### Response\nA [**payload**](#def-payload) containing one specific [HTTP Response](http://www.w3.org/TR/di-gloss/#def-http-response).\n\n<a name=\"def-resource\"></a>\n### Resource\nAn API [**resource**](http://www.w3.org/TR/di-gloss/#def-resource) specified by\nits *URI*. It can also refer to a [**set of resources**](#def-resource)\nmatching one [**URI template**](#def-uri-template).\n\n<a name=\"def-resource-model\"></a>\n### Resource Model\nOne [**manifestation of a resource**](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) in the\nform of a [payload](#def-payload). A resource model is an example\nrepresentation of its resource. Can be referenced later in the place of a\n[payload](#def-payload).\n\n<a name=\"def-resource-set\"></a>\n### Resource Set\nA set of API [**resources**](http://www.w3.org/TR/di-gloss/#def-resource). Its\n*URI* matches one specific [**URI template**](#def-uri-template).\n\n<a name=\"def-trait\"></a>\n### Trait\nA quality or characteristic of an API Blueprint SECTION.\n\n<a name=\"def-schema\"></a>\n### Schema\nA **validation schema** in a form of an [**asset**](#def-asset) used to validate (or describe) a [**message-body**](#def-message-body).\n\n<a name=\"def-uri-template\"></a>\n### URI template\nA compact sequence of characters for describing a range of **Uniform Resource Identifiers** through **variable** expansion, see [**RFC 6570**](http://tools.ietf.org/html/rfc6570).\n\n## Additional resources\n\n+ [HTTP/1.1 Terminology](http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html#sec1.3)\n+ [W3C Glossary of Terms for Device Independence](http://www.w3.org/TR/di-gloss)\n+ [Know your HTTP well](https://github.com/for-GET/know-your-http-well)\n+ [Markdown Syntax for Object Notation][MSON]\n\n\n\n[MSON]: https://github.com/apiaryio/mson\n\n"
  },
  {
    "path": "LICENSE",
    "content": "(The MIT License)\n\nCopyright (c) 2014 Apiary Inc. <support@apiary.io>.\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."
  },
  {
    "path": "README.md",
    "content": "![logo](assets/logo_apiblueprint.png)\n\n# API Blueprint\n### API Design for Humans\n\nA powerful high-level API design language for web APIs.\n\nAPI Blueprint is simple and accessible to everybody involved in the API design\nlifecycle. Its syntax is concise yet expressive.\n\nWith API Blueprint you can quickly prototype and model APIs to be created or\ndescribe already deployed mission-critical APIs. From a [car][tesla] to the\nlargest Content Distribution Network (CDN) in the world.\n\nThe API Blueprint is built to encourage dialogue and collaboration between\nproject stakeholders, developers and customers at any point in the API\nlifecycle. At the same time, the API Blueprint [tools][] provide the support to\nachieve the goals be it API development, governance or delivery.\n\n![API Blueprint Lifecycle](assets/lifecycle.png)\n\n[tesla]: https://github.com/timdorr/model-s-api/blob/master/apiary.apib\n[tools]: http://apiblueprint.org/tools.html\n\n## Open Source\nAPI Blueprint is completely open sourced under the MIT license.\nAny [contribution][contribute] is highly appreciated.\n\n[contribute]: #contribute\n\n## At home on GitHub\nAPI Blueprint language is recognized by GitHub. You can\n[search for API Blueprint][search] or use the `apib` language identifier for\n[syntax highlighting][gfm].\n\n[search]: https://github.com/search?utf8=%E2%9C%93&q=language%3A%22API+Blueprint%22&type=Repositories&ref=advsearch&l=API+Blueprint&l=\n\n[gfm]: https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting\n\n## Getting started\nAll it takes to describe an endpoint of your API is to write:\n\n```apib\n# GET /message\n+ Response 200 (text/plain)\n\n        Hello World!\n```\n\nin your favorite plain text editor.\n\nWith this blueprint you can already get a [mock][], [documentation][] and\n[test][] for your API before you even start coding.\n\nTo learn more about the API Blueprint syntax jump directly to the\n[API Blueprint Tutorial][tutorial] or take a look at some [examples][].\n\n[mock]: http://docs.apibstart.apiary.io/#reference/0/message/get?console=1\n[documentation]: https://apiblueprint.org/documentation/\n[test]: http://dredd.readthedocs.org/en/latest/\n[tutorial]: Tutorial.md\n[examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples\n\n## Media Type\nThe media type for API Blueprint is `text/vnd.apiblueprint`.\n\n## Learn more\n- [Tutorial][tutorial]\n- [Advanced Tutorial][advanced_tutorial]\n- [Examples][examples]\n- [Wiki][wiki]\n- [Glossary of Terms][glossary]\n- [Specification][specification]\n- [List of Tools][tools]\n- [Developers][developers]\n\n[advanced_tutorial]: Advanced%20Tutorial.md\n[glossary]: Glossary%20of%20Terms.md\n[specification]: API%20Blueprint%20Specification.md\n[wiki]: https://github.com/apiaryio/api-blueprint/wiki\n[developers]: https://apiblueprint.org/developers.html\n\n## Future\nThe plans for API Blueprint are completely tracked on GitHub – see the\n[API Blueprint Roadmap][roadmap].\n\n[roadmap]: https://github.com/apiaryio/api-blueprint/wiki/Roadmap\n\n## Developers\nBuilding tools for API Blueprint is possible thanks to its machine-friendly face\nprovided by API Blueprint parser.\n\nIf you are interested in building tools for API Blueprint check out the\n[Developing tools for API Blueprint][developers].\n\n## Contribute\nFeel free report problems or propose new ideas using the API Blueprint GitHub\n[issues][].\n\nWe use an RFC process for proposing any substantial changes to the API\nBlueprint language, specification and/or parsers.\n\nIf you would like to propose a change, please consult our\n[RFC process][rfc].\n\n[issues]: https://github.com/apiaryio/api-blueprint/issues\n[rfc]: https://github.com/apiaryio/api-blueprint-rfcs\n\n## Get in Touch\n- [@apiblueprint](https://twitter.com/apiblueprint)\n- [Slack](https://apiblueprint-slack.herokuapp.com/)\n- [Stack Overflow](http://stackoverflow.com/questions/tagged/apiblueprint)\n- [GitHub Issues][issues]\n\n## License\nMIT License. See the [LICENSE](https://github.com/apiaryio/api-blueprint/blob/master/LICENSE)\nfile.\n"
  },
  {
    "path": "Tutorial.md",
    "content": "# API Blueprint Tutorial\n\nWelcome to an API Blueprint Tutorial! This tutorial will take you through the\nbasics of the API Blueprint language. We’re going to build an API blueprint\nstep by step for a service called Polls – a simple API allowing consumers to\nview polls and vote in them. You can take a look at the \n[full version][Poll API Blueprint] of the blueprint used in this tutorial for\nreference.\n\n> **Note:** **Additional API Blueprint Resources**\n>\n> + [Language Specification][specification]\n> + [Examples][API Blueprint Examples]\n> + [Glossary of Terms][API Blueprint Glossary of Terms]\n> + [API Blueprint Map][map]\n> + [Tools for API Blueprint][Tooling Section]\n\n## API Blueprint\n\nThe first step for creating a blueprint is to specify the API Name and\nmetadata. This step looks as follows:\n\n```apib\nFORMAT: 1A\n\n# Polls\n\nPolls is a simple API allowing consumers to view polls and vote in them.\n```\n\n## Metadata\n\nThe blueprint starts with a metadata section. In this case we have specified\nthat `FORMAT` has the value of `1A`. The format keyword denotes the version of\nthe API Blueprint.\n\n## API Name & Description\n\nThe first heading in the blueprint serves as the name of your API, which in\nthis case is \"Polls\". Headings start with one or more `#` symbols followed by a\ntitle. The API Name here uses one hash to distinguish it as the first level.\nThe number of `#` you use will determine the level of the heading.\n\nFollowing the heading is a description of the API. You may use further headings\nto break up the description section.\n\n## Resource Groups\n\nNow it's time to start documenting the API resources. Using the `Group` keyword\nat the start of a heading, we've created a group of related resources.\n\n```apib\n# Group Questions\n\nResources related to questions in the API.\n```\n\n## Resource\n\nWithin the questions resource group, we have a resource called \"Question\nCollection\". This resource allows you to view a list of questions. The heading\nspecifies the URI used to access the resource inside of square brackets at the\nend of the heading.\n\n```apib\n## Question Collection [/questions]\n```\n\n### Actions\n\nAPI Blueprint allows you to specify each action you may make on a resource. An\naction is specified with a sub-heading inside of a resource with the name of\nthe action followed by the HTTP method.\n\n```apib\n### List All Questions [GET]\n```\n\nAn action should include at least one response from the server which must\ninclude a status code and may contain a body. A response is defined as a list\nitem within an action. Lists are created by preceding list items with either a\n`+`, `*` or `-`.\n\nThis action returns a `200` status code along with a JSON body.\n\n```apib\n+ Response 200 (application/json)\n\n        [\n            {\n                \"question\": \"Favourite programming language?\",\n                \"published_at\": \"2014-11-11T08:40:51.620Z\",\n                \"url\": \"/questions/1\",\n                \"choices\": [\n                    {\n                        \"choice\": \"Swift\",\n                        \"url\": \"/questions/1/choices/1\",\n                        \"votes\": 2048\n                    }, {\n                        \"choice\": \"Python\",\n                        \"url\": \"/questions/1/choices/2\",\n                        \"votes\": 1024\n                    }, {\n                        \"choice\": \"Objective-C\",\n                        \"url\": \"/questions/1/choices/3\",\n                        \"votes\": 512\n                    }, {\n                        \"choice\": \"Ruby\",\n                        \"url\": \"/questions/1/choices/4\",\n                        \"votes\": 256\n                    }\n                ]\n            }\n        ]\n```\n\n> **Note:** Specifying the media type after the response status code generates\n> a `Content-Type` HTTP header. You do not have to explicitly specify the\n> `Content-Type` header.\n\nThe polls resource has a second action which allows you to create a new\nquestion. This action includes a description showing the structure you would\nsend to the server to perform this action.\n\n```apib\n### Create a New Question [POST]\n\nYou may create your own question using this action. It takes a JSON object\ncontaining a question and a collection of answers in the form of choices.\n\n+ question (string) - The question\n+ choices (array[string]) - A collection of choices.\n```\n\nThis action takes a JSON payload as part of the request as follows:\n\n```apib\n+ Request (application/json)\n\n            {\n                \"question\": \"Favourite programming language?\",\n                \"choices\": [\n                    \"Swift\",\n                    \"Python\",\n                    \"Objective-C\",\n                    \"Ruby\"\n                ]\n            }\n```\n\nThis example returns a `201` status code, along with HTTP headers and a body.\n\n```apib\n+ Response 201 (application/json)\n\n    + Headers\n\n            Location: /questions/1\n\n    + Body\n\n                {\n                    \"question\": \"Favourite programming language?\",\n                    \"published_at\": \"2014-11-11T08:40:51.620Z\",\n                    \"url\": \"/questions/1\",\n                    \"choices\": [\n                        {\n                            \"choice\": \"Swift\",\n                            \"url\": \"/questions/1/choices/1\",\n                            \"votes\": 0\n                        }, {\n                            \"choice\": \"Python\",\n                            \"url\": \"/questions/1/choices/2\",\n                            \"votes\": 0\n                        }, {\n                            \"choice\": \"Objective-C\",\n                            \"url\": \"/questions/1/choices/3\",\n                            \"votes\": 0\n                        }, {\n                            \"choice\": \"Ruby\",\n                            \"url\": \"/questions/1/choices/4\",\n                            \"votes\": 0\n                        }\n                    ]\n                }\n```\n\nThe next resource is “Question”, which represents a single question.\n\n```apib\n## Question [/questions/{question_id}]\n```\n\n### URI Template\n\nThe URI for the “Question” resource uses a variable component, expressed by\n[URI Template][]. In this case, there is an ID variable called `question_id`,\nrepresented in the URI template as `{question_id}`.\n\n<a id=\"uri-parameters\"></a>\n### URI Parameters\n\nURI parameters should describe the URI using a list of Parameters. For\n“Question” it would be as follows:\n\n```apib\n+ Parameters\n    + question_id (number) - ID of the Question in the form of an integer\n```\n\nThe `question_id` variable of the URI template is a parameter for every action\non this resource. It's defined here using an arbitrary type `number`, followed\nby a description for the parameter.\n\n> Refer to API Blueprint Specification's [URI Parameters Section][] for more\n> examples.\n\n### Actions\n\nThis resource has an action to retrieve the question's detail.\n\n```apib\n### View a Questions Detail [GET]\n\n+ Response 200 (application/json)\n\n            {\n                \"question\": \"Favourite programming language?\",\n                \"published_at\": \"2014-11-11T08:40:51.620Z\",\n                \"url\": \"/questions/1\",\n                \"choices\": [\n                    {\n                        \"choice\": \"Swift\",\n                        \"url\": \"/questions/1/choices/1\",\n                        \"votes\": 2048\n                    }, {\n                        \"choice\": \"Python\",\n                        \"url\": \"/questions/1/choices/2\",\n                        \"votes\": 1024\n                    }, {\n                        \"choice\": \"Objective-C\",\n                        \"url\": \"/questions/1/choices/3\",\n                        \"votes\": 512\n                    }, {\n                        \"choice\": \"Ruby\",\n                        \"url\": \"/questions/1/choices/4\",\n                        \"votes\": 256\n                    }\n                ]\n            }\n```\n\n#### Response Without a Body\n\nThis resource has a delete action. The server will return a 204 response\nwithout a body.\n\n```apib\n### Delete [DELETE]\n\n+ Response 204\n```\n\n## Complete Blueprint\n\nYou can find an [implementation](http://github.com/apiaryio/polls-api) of this\nAPI at http://polls.apiblueprint.org/ along with the complete \n[Poll API Blueprint][] in the [API Blueprint Examples][] repository. You can\nalso enjoy it [rendered on Apiary][].\n\n> **Note:** Take a look at the [API Blueprint Glossary of Terms][] if you need\n> clarification of some of the terms used though this document.\n\n## API Blueprint Tools\n\nVisit the [Tooling Section][] of [apiblueprint.org][] to find tools to use with\nAPI Blueprints.\n\n[GitHub Gists]:                     https://gist.github.com\n[API Blueprint Glossary of Terms]:  https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md\n[API Blueprint Identifier]:         https://github.com/apiaryio/api-blueprint/blob/1A/API%20Blueprint%20Specification.md#Identifiers\n[HTTP Request Method]:              https://github.com/for-GET/know-your-http-well/blob/master/methods.md\n[status code]:                      https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md\n[message-headers]:                  https://github.com/for-GET/know-your-http-well/blob/master/headers.md\n[payload]:                          https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#payload\n[URI Template]:                     https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#uri-template\n[URI Parameters Section]:           https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-uriparameters-section\n[Markdown pre-formatted code blocks]: http://daringfireball.net/projects/markdown/syntax#precode\n[URI Parameters]: #uri-parameters\n[API Blueprint Examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples\n[Poll API Blueprint]: https://raw.github.com/apiaryio/api-blueprint/master/examples/Polls%20API.md\n[rendered on Apiary]: http://docs.pollsapi.apiary.io\n[Tooling Section]: http://apiblueprint.org/tools.html\n[apiblueprint.org]: http://apiblueprint.org\n[specification]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md\n[map]: https://github.com/apiaryio/api-blueprint/wiki/API-Blueprint-Map\n"
  },
  {
    "path": "examples/01. Simplest API.md",
    "content": "FORMAT: 1A\n\n# The Simplest API\nThis is one of the simplest APIs written in the **API Blueprint**. One plain\nresource combined with a method and that's it! We will explain what is going on\nin the next installment - \n[Resource and Actions](02.%20Resource%20and%20Actions.md).\n\n**Note:** As we progress through the examples, do not also forget to view the\n[Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md)\ncode to see what is really going on in the API Blueprint, as opposed to just\nseeing the output of the Github Markdown parser.\n\nAlso please keep in mind that every single example in this course is a **real\nAPI Blueprint** and as such you can **parse** it with the \n[API Blueprint parser](https://github.com/apiaryio/drafter) or one of its\n[bindings](https://github.com/apiaryio/drafter#bindings).\n\n## API Blueprint\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md)\n+ [Next: Resource and Actions](02.%20Resource%20and%20Actions.md)\n\n# GET /message\n+ Response 200 (text/plain)\n\n        Hello World!\n"
  },
  {
    "path": "examples/02. Resource and Actions.md",
    "content": "FORMAT: 1A\n\n# Resource and Actions API\nThis API example demonstrates how to define a resource with multiple actions.\n\n## API Blueprint\n+ [Previous: The Simplest API](01.%20Simplest%20API.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/02.%20Resource%20and%20Actions.md)\n+ [Next: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md)\n\n# /message\nThis is our [resource](http://www.w3.org/TR/di-gloss/#def-resource). It is\ndefined by its\n[URI](http://www.w3.org/TR/di-gloss/#def-uniform-resource-identifier) or, more\nprecisely, by its [URI Template](http://tools.ietf.org/html/rfc6570).\n\nThis resource has no actions specified but we will fix that soon.\n\n## GET\nHere we define an action using the `GET` [HTTP request method](http://www.w3schools.com/tags/ref_httpmethods.asp) for our resource `/message`.\n\nAs with every good action it should return a\n[response](http://www.w3.org/TR/di-gloss/#def-http-response). A response always\nbears a status code. Code 200 is great as it means all is green. Responding\nwith some data can be a great idea as well so let's add a plain text message to\nour response.\n\n+ Response 200 (text/plain)\n\n        Hello World!\n\n## PUT\nOK, let's add another action. This time to put new data to our resource\n(essentially an update action). We will need to send something in a\n[request](http://www.w3.org/TR/di-gloss/#def-http-request) and then send a\nresponse back confirming the posting was a success (_HTTP Status Code 204 ~\nResource updated successfully, no content is returned_).\n\n+ Request (text/plain)\n\n        All your base are belong to us.\n\n+ Response 204\n"
  },
  {
    "path": "examples/03. Named Resource and Actions.md",
    "content": "FORMAT: 1A\n\n# Named Resource and Actions API\nThis API example demonstrates how to name a resource and its actions, to give\nthe reader a better idea about what the resource is used for.\n\n## API Blueprint\n+ [Previous: Resource and Actions](02.%20Resource%20and%20Actions.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/03.%20Named%20Resource%20and%20Actions.md)\n+ [Next: Grouping Resources](04.%20Grouping%20Resources.md)\n\n# My Message [/message]\nOK, `My Message` probably isn't the best name for our resource but it will do\nfor now. Note the URI `/message` is enclosed in square brackets.\n\n## Retrieve a Message [GET]\nNow this is informative! No extra explanation needed here. This action clearly\nretrieves the message.\n\n+ Response 200 (text/plain)\n\n        Hello World!\n\n## Update a Message [PUT]\n`Update a message` - nice and simple naming is the best way to go.\n\n+ Request (text/plain)\n\n        All your base are belong to us.\n\n+ Response 204\n"
  },
  {
    "path": "examples/04. Grouping Resources.md",
    "content": "FORMAT: 1A\n\n# Grouping Resources API\nThis API example demonstrates how to group resources and form **groups of\nresources**. You can create as many or as few groups as you like. If you do not\ncreate any group all your resources will be part of an \"unnamed\" group.\n\n## API Blueprint\n+ [Previous: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/04.%20Grouping%20Resources.md)\n+ [Next: Responses](05.%20Responses.md)\n\n# Group Messages\nGroup of all messages-related resources.\n\nThis is the first group of resources in this document. It is **recognized** by\nthe **keyword `group`** and its name is `Messages`.\n\nAny following resource definition is considered to be a part of this group\nuntil another group is defined. It is **customary** to increase header level of\nresources (and actions) nested under a resource.\n\n## My Message [/message]\n\n### Retrieve a Message [GET]\n\n+ Response 200 (text/plain)\n\n        Hello World!\n\n### Update a Message [PUT]\n\n+ Request (text/plain)\n\n        All your base are belong to us.\n\n+ Response 204\n\n# Group Users\nGroup of all user-related resources.\n\nThis is the second group in this blueprint. For now, no resources were defined\nhere and as such we will omit it from the next installment of this course.\n"
  },
  {
    "path": "examples/05. Responses.md",
    "content": "FORMAT: 1A\n\n# Responses API\nIn this API example we will discuss what information a response can bear and\nhow to define multiple responses. Technically a response is represented by a\npayload that is sent back in response to a request.\n\n## API Blueprint\n+ [Previous: Grouping Resources](04.%20Grouping%20Resources.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/05.%20Responses.md)\n+ [Next: Requests](06.%20Requests.md)\n\n# Group Messages\nGroup of all messages-related resources.\n\n## My Message [/message]\n\n### Retrieve a Message [GET]\nThis action has **two** responses defined: One returning plain text and the\nother a JSON representation of our resource. Both have the same HTTP status\ncode. Also both responses bear additional information in the form of a custom\nHTTP header. Note that both responses have set the `Content-Type` HTTP header\njust by specifying `(text/plain)` or `(application/json)` in their respective\nsignatures.\n\n+ Response 200 (text/plain)\n\n    + Headers\n\n            X-My-Message-Header: 42\n\n    + Body\n\n            Hello World!\n\n+ Response 200 (application/json)\n\n    + Headers\n\n            X-My-Message-Header: 42\n\n    + Body\n\n            { \"message\": \"Hello World!\" }\n\n### Update a Message [PUT]\n\n+ Request (text/plain)\n\n        All your base are belong to us.\n\n+ Response 204\n"
  },
  {
    "path": "examples/06. Requests.md",
    "content": "FORMAT: 1A\n\n# Requests API\nFollowing the [Responses](05.%20Responses.md) example, this API will show you\nhow to define multiple requests and what data these requests can bear. Let's\ndemonstrate multiple requests on a trivial example of content negotiation.\n\n## API Blueprint\n+ [Previous: Responses](05.%20Responses.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/06.%20Requests.md)\n+ [Next: Parameters](07.%20Parameters.md)\n\n# Group Messages\nGroup of all messages-related resources.\n\n## My Message [/message]\n\n### Retrieve a Message [GET]\nIn API Blueprint, _requests_ can hold exactly the same kind of information and\ncan be described using exactly the same structure as _responses_, only with\ndifferent signature – using the `Request` keyword. The string that follows\nafter the `Request` keyword is a request identifier. Again, using explanatory\nand simple naming is the best way to go.\n\n+ Request Plain Text Message\n\n    + Headers\n\n            Accept: text/plain\n\n+ Response 200 (text/plain)\n\n    + Headers\n\n            X-My-Message-Header: 42\n\n    + Body\n\n            Hello World!\n\n+ Request JSON Message\n\n    + Headers\n\n            Accept: application/json\n\n+ Response 200 (application/json)\n\n    + Headers\n\n            X-My-Message-Header: 42\n\n    + Body\n\n            { \"message\": \"Hello World!\" }\n\n### Update a Message [PUT]\n\n+ Request Update Plain Text Message (text/plain)\n\n        All your base are belong to us.\n\n+ Request Update JSON Message (application/json)\n\n        { \"message\": \"All your base are belong to us.\" }\n\n+ Response 204\n"
  },
  {
    "path": "examples/07. Parameters.md",
    "content": "FORMAT: 1A\n\n# Parameters API\nIn this installment of the API Blueprint course we will discuss how to describe URI parameters.\n\nBut first let's add more messages to our system. For that we would need\nintroduce an message identifier – id. This id will be our parameter when\ncommunicating with our API about messages.\n\n## API Blueprint\n+ [Previous: Requests](06.%20Requests.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/07.%20Parameters.md)\n+ [Next: Attributes](08.%20Attributes.md)\n\n# Group Messages\nGroup of all messages-related resources.\n\n## My Message [/message/{id}]\nHere we have added the message `id` parameter as an \n[URI Template variable](http://tools.ietf.org/html/rfc6570) in the Message\nresource's URI. Note the parameter name `id` is enclosed in curly brackets. We\nwill discuss this parameter in the `Parameters` section below, where we will\nalso set its example value to `1` and declare it of an arbitrary 'number' type.\n\n+ Parameters\n\n    + id: 1 (number) - An unique identifier of the message.\n\n### Retrieve a Message [GET]\n\n+ Request Plain Text Message\n\n    + Headers\n\n            Accept: text/plain\n\n+ Response 200 (text/plain)\n\n    + Headers\n\n            X-My-Message-Header: 42\n\n    + Body\n\n            Hello World!\n\n+ Request JSON Message\n\n    + Headers\n\n            Accept: application/json\n\n+ Response 200 (application/json)\n\n    + Headers\n\n            X-My-Message-Header: 42\n\n    + Body\n\n            {\n              \"id\": 1,\n              \"message\": \"Hello World!\"\n            }\n\n### Update a Message [PUT]\n\n+ Request Update Plain Text Message (text/plain)\n\n        All your base are belong to us.\n\n+ Request Update JSON Message (application/json)\n\n        { \"message\": \"All your base are belong to us.\" }\n\n+ Response 204\n\n## All My Messages [/messages{?limit}]\nA resource representing all of my messages in the system.\n\nWe have added the query URI template parameter - `limit`. This parameter is\nused for limiting the number of results returned by some actions on this\nresource. It does not affect every possible action of this resource, therefore\nwe will discuss it only at the particular action level below.\n\n### Retrieve all Messages [GET]\n\n+ Parameters\n\n    + limit (number, optional) - The maximum number of results to return.\n        + Default: `20`\n\n+ Response 200 (application/json)\n\n        [\n          {\n            \"id\": 1,\n            \"message\": \"Hello World!\"\n          },\n          {\n            \"id\": 2,\n            \"message\": \"Time is an illusion. Lunchtime doubly so.\"\n          },\n          {\n            \"id\": 3,\n            \"message\": \"So long, and thanks for all the fish.\"\n          }\n        ]\n"
  },
  {
    "path": "examples/08. Attributes.md",
    "content": "FORMAT: 1A\n\n# Attributes API\nThis API example demonstrates how to describe body attributes of a request or\nresponse message.\n\nIn this case, the description is complementary (and duplicate!) to the provided\nJSON example in the body section. The \n[Advanced Attributes](09.%20Advanced%20Attributes.md) API example will\ndemonstrate how to avoid duplicates and how to reuse attribute descriptions.\n\n## API Blueprint\n+ [Previous: Parameters](07.%20Parameters.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/08.%20Attributes.md)\n+ [Next: Advanced Attributes](09.%20Advanced%20Attributes.md)\n\n# Group Coupons\n\n## Coupon [/coupons/{id}]\nA coupon contains information about a percent-off or amount-off discount you\nmight want to apply to a customer.\n\n### Retrieve a Coupon [GET]\nRetrieves the coupon with the given ID.\n\n+ Response 200 (application/json)\n\n    + Attributes (object)\n        + id: 250FF (string, required)\n        + created: 1415203908 (number) - Time stamp\n        + percent_off: 25 (number)\n\n            A positive integer between 1 and 100 that represents the discount\n            the coupon will apply.\n\n        + redeem_by (number) - Date after which the coupon can no longer be redeemed\n\n    + Body\n\n            {\n                \"id\": \"250FF\",\n                \"created\": 1415203908,\n                \"percent_off\": 25,\n                \"redeem_by\": null\n            }\n"
  },
  {
    "path": "examples/09. Advanced Attributes.md",
    "content": "FORMAT: 1A\n\n# Advanced Attributes API\nImproving the previous [Attributes](08.%20Attributes.md) description example,\nthis API example describes the `Coupon` resource attributes (data structure)\nregardless of the serialization format. These attributes can be later\nreferenced using the resource name.\n\nThese attributes are then reused in the `Retrieve a Coupon` action. Since they\ndescribe the complete message, no explicit JSON body example is needed.\n\nMoving forward, the `Coupon` resource data structure is then reused when\ndefining the attributes of the coupons collection resource – `Coupons`.\n\nThe `Create a Coupon` action also demonstrate the description of request\nattributes – once defined, these attributes are implied on every `Create a\nCoupon` request unless the request specifies otherwise. Apparently, the\ndescription of action attributes is somewhat duplicate to the definition of\n`Coupon` resource attributes. We will address this in the next \n[Data Structures](10.%20Data%20Structures.md) example.\n\n## API Blueprint\n+ [Previous: Attributes](08.%20Attributes.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/09.%20Advanced%20Attributes.md)\n+ [Next: Data Structures](10.%20Data%20Structures.md)\n\n# Group Coupons\n\n## Coupon [/coupons/{id}]\nA coupon contains information about a percent-off or amount-off discount you\nmight want to apply to a customer.\n\n+ Parameters\n    + id (string)\n\n        The ID of the desired coupon.\n\n+ Attributes (object)\n    + id: 250FF (string, required)\n    + created: 1415203908 (number) - Time stamp\n    + percent_off: 25 (number)\n\n        A positive integer between 1 and 100 that represents the discount the coupon will apply.\n\n    + redeem_by (number) - Date after which the coupon can no longer be redeemed\n\n### Retrieve a Coupon [GET]\nRetrieves the coupon with the given ID.\n\n+ Response 200 (application/json)\n    + Attributes (Coupon)\n\n## Coupons [/coupons{?limit}]\n\n+ Attributes (array[Coupon])\n\n### List all Coupons [GET]\nReturns a list of your coupons.\n\n+ Parameters\n    + limit (number, optional)\n\n        A limit on the number of objects to be returned. Limit can range\n        between 1 and 100 items.\n\n        + Default: `10`\n\n+ Response 200 (application/json)\n    + Attributes (Coupons)\n\n### Create a Coupon [POST]\nCreates a new Coupon.\n\n+ Attributes (object)\n    + percent_off: 25 (number)\n    + redeem_by (number)\n\n+ Request (application/json)\n\n+ Response 200 (application/json)\n    + Attributes (Coupon)\n"
  },
  {
    "path": "examples/10. Data Structures.md",
    "content": "FORMAT: 1A\n\n# Data Structures API\nFollowing [Advanced Attributes](09.%20Advanced%20Attributes.md), this example\ndemonstrates defining arbitrary data structure to be reused by various\nattribute descriptions.\n\nSince a portion of the `Coupon` data structure is shared between the `Coupon`\ndefinition itself and the `Create a Coupon` action, it was separated into a\n`Coupon Base` data structure in the `Data Structures` API Blueprint Section.\nDoing so enables us to reuse it as a base-type of other attribute definitions.\n\n## API Blueprint\n+ [Previous: Advanced Attributes](09.%20Advanced%20Attributes.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/10.%20Data%20Structures.md)\n+ [Next: Resource Model](11.%20Resource%20Model.md)\n\n# Group Coupons\n\n## Coupon [/coupons/{id}]\nA coupon contains information about a percent-off or amount-off discount you\nmight want to apply to a customer.\n\n+ Parameters\n    + id (string)\n\n        The ID of the desired coupon.\n\n+ Attributes (Coupon Base)\n    + id: 250FF (string, required)\n    + created: 1415203908 (number) - Time stamp\n\n### Retrieve a Coupon [GET]\nRetrieves the coupon with the given ID.\n\n+ Response 200 (application/json)\n    + Attributes (Coupon)\n\n## Coupons [/coupons{?limit}]\n\n+ Attributes (array[Coupon])\n\n### List all Coupons [GET]\nReturns a list of your coupons.\n\n+ Parameters\n    + limit (number, optional)\n\n        A limit on the number of objects to be returned. Limit can range\n        between 1 and 100 items.\n\n        + Default: `10`\n\n+ Response 200 (application/json)\n    + Attributes (Coupons)\n\n### Create a Coupon [POST]\nCreates a new Coupon.\n\n+ Attributes (Coupon Base)\n\n+ Request (application/json)\n\n+ Response 200 (application/json)\n    + Attributes (Coupon)\n\n# Data Structures\n\n## Coupon Base (object)\n+ percent_off: 25 (number)\n\n    A positive integer between 1 and 100 that represents the discount the\n    coupon will apply.\n\n+ redeem_by (number) - Date after which the coupon can no longer be redeemed\n"
  },
  {
    "path": "examples/11. Resource Model.md",
    "content": "FORMAT: 1A\n\n# Resource Model API\nResource model is a [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation).\nOne particular representation of your resource.\n\nFurthermore, in API Blueprint, any `resource model` you have defined can be\nreferenced in a request or response section, saving you lots of time\nmaintaining your API blueprint. You simply define a resource model as any\npayload (e.g. [request](https://github.com/apiaryio/api-blueprint/blob/master/examples/06.%20Requests.md)\nor [response](https://github.com/apiaryio/api-blueprint/blob/master/examples/5.%20Responses.md))\nand then reference it later where you would normally write a `request` or\n`response`.\n\n## API Blueprint\n+ [Previous: Data Structures](10.%20Data%20Structures.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/11.%20Resource%20Model.md)\n+ [Next: Advanced Action](12.%20Advanced%20Action.md)\n\n# Group Messages\nGroup of all messages-related resources.\n\n## My Message [/message]\n\n+ Model (application/vnd.siren+json)\n\n    This is the `application/vnd.siren+json` message resource representation.\n\n    + Headers\n\n            Location: http://api.acme.com/message\n\n    + Body\n\n            {\n              \"class\": [ \"message\" ],\n              \"properties\": {\n                    \"message\": \"Hello World!\"\n              },\n              \"links\": [\n                    { \"rel\": \"self\" , \"href\": \"/message\" }\n              ]\n            }\n\n### Retrieve a Message [GET]\nAt this point we will utilize our `Message` resource model and reference it in\n`Response 200`.\n\n+ Response 200\n\n    [My Message][]\n\n### Update a Message [PUT]\n\n+ Request Update Plain Text Message (text/plain)\n\n        All your base are belong to us.\n\n+ Request Update JSON Message (application/json)\n\n        { \"message\": \"All your base are belong to us.\" }\n\n+ Response 204\n\n"
  },
  {
    "path": "examples/12. Advanced Action.md",
    "content": "FORMAT: 1A\n\n# Advanced Action API\nA resource action is – in fact – a state transition. This API example\ndemonstrates an action - state transition - to another resource.\n\n## API Blueprint\n+ [Previous: Resource Model](11.%20Resource%20Model.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/12.%20Advanced%20Action.md)\n+ [Next: Named Endpoints](13.%20Named%20Endpoints.md)\n\n# Tasks [/tasks/tasks{?status,priority}]\n\n+ Parameters\n    + status (string)\n    + priority (number)\n\n## List All Tasks [GET]\n\n+ Response 200 (application/json)\n\n        [\n            {\n                \"id\": 123,\n                \"name\": \"Exercise in gym\",\n                \"done\": false,\n                \"type\": \"task\"\n            },\n            {\n                \"id\": 124,\n                \"name\": \"Shop for groceries\",\n                \"done\": true,\n                \"type\": \"task\"\n            }\n        ]\n\n## Retrieve Task [GET /task/{id}]\nThis is a state transition to another resource.\n\n+ Parameters\n    + id (string)\n\n+ Response 200 (application/json)\n\n        {\n            \"id\": 123,\n            \"name\": \"Go to gym\",\n            \"done\": false,\n            \"type\": \"task\"\n        }\n\n## Delete Task [DELETE /task/{id}]\n\n+ Parameters\n    + id (string)\n\n+ Response 204\n"
  },
  {
    "path": "examples/13. Named Endpoints.md",
    "content": "FORMAT: 1A\n\n# Named Endpoints API\nThis API example demonstrates how to define a standalone endpoint with an identifier.\n\n## API Blueprint\n+ [Previous: Advanced Action](12.%20Advanced%20Action.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/13.%20Named%20Endpoints.md)\n+ [Next: JSON Schema](14.%20JSON%20Schema.md)\n\n# Group Quick start\n\n## Create message [POST /messages]\n\nStart out by creating a message for the world to see.\n\n+ Request (application/json)\n\n        { \"message\": \"Hello World!\" }\n\n+ Response 201\n\n    + Headers\n\n            Location: /messages/1337\n\n## Create a new task [POST /tasks]\n\nNow create a task that you need to do at a later date.\n\n+ Request (application/json)\n\n        {\n            \"name\": \"Exercise in gym\",\n            \"done\": false,\n            \"type\": \"task\"\n        }\n\n+ Response 201\n\n    + Headers\n\n            Location: /tasks/1992\n"
  },
  {
    "path": "examples/14. JSON Schema.md",
    "content": "FORMAT: 1A\n\n# JSON Schema\nEvery request and response can have a schema. Below you will find examples\nusing [JSON Schema](http://json-schema.org/) to describe the format of request\nand response body content.\n\n## API Blueprint\n+ [Previous: Named Endpoints](13.%20Named%20Endpoints.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/14.%20JSON%20Schema.md)\n+ [Next: Advanced JSON Schema](15.%20Advanced%20JSON%20Schema.md)\n\n# Notes [/notes/{id}]\n\n+ Parameters\n\n    + id: abc123 (required) - Unique identifier for a note\n\n## Get a note [GET]\nGets a single note by its unique identifier.\n\n+ Response 200 (application/json)\n\n    + Body\n\n            {\n                \"id\": \"abc123\",\n                \"title\": \"This is a note\",\n                \"content\": \"This is the note content.\"\n                \"tags\": [\n                    \"todo\",\n                    \"home\"\n                ]\n            }\n\n    + Schema\n\n            {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"id\": {\n                        \"type\": \"string\"\n                    },\n                    \"title\": {\n                        \"type\": \"string\"\n                    },\n                    \"content\": {\n                        \"type\": \"string\"\n                    },\n                    \"tags\": {\n                        \"type\": \"array\",\n                        \"items\": {\n                            \"type\": \"string\"\n                        }\n                    }\n                }\n            }\n\n## Update a note [PATCH]\nModify a note's data using its unique identifier. You can edit the `title`,\n`content`, and `tags`.\n\n+ Request (application/json)\n\n    + Body\n\n            {\n                \"title\": \"This is another note\",\n                \"tags\": [\n                    \"todo\",\n                    \"work\"\n                ]\n            }\n\n    + Schema\n\n            {\n                \"type\": \"object\",\n                \"properties\": {\n                    \"title\": {\n                        \"type\": \"string\"\n                    },\n                    \"content\": {\n                        \"type\": \"string\"\n                    },\n                    \"tags\": {\n                        \"type\": \"array\",\n                        \"items\": {\n                            \"type\": \"string\"\n                        }\n                    }\n                },\n                \"additionalProperties\": false\n            }\n\n+ Response 204\n"
  },
  {
    "path": "examples/15. Advanced JSON Schema.md",
    "content": "FORMAT: 1A\n\n# Advanced JSON Schema\nThe JSON body and JSON Schema for a request or response can be generated from\nthe attributes section MSON data structure. The generated schema can also be\noverridden by providing an explicit schema, as you can see in the examples\nbelow.\n\n## API Blueprint\n+ [Previous: JSON Schema](14.%20JSON%20Schema.md)\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/15.%20Advanced%20JSON%20Schema.md)\n\n# Notes [/notes/{id}]\n\n+ Parameters\n\n    + id: abc123 (required) - Unique identifier for a note\n\n## Get a note [GET]\nGets a single note by its unique identifier.\n\n+ Response 200 (application/json)\n\n    + Attributes\n\n        + id: abc123\n        + title: This is a note\n        + content: This is the note content.\n        + tags: todo, home (array[string])\n\n## Update a note [PATCH]\nModify a note's data using its unique identifier. You can edit the `title`,\n`content`, and `tags`.\n\n+ Request (application/json)\n\n    + Attributes\n\n        + title: This is another note\n        + content\n        + tags: todo, work (array[string])\n\n    + Schema\n\n            {\n                \"type\": \"object\",\n                \"description\": \"This is a custom schema!\",\n                \"properties\": {\n                    \"title\": {\n                        \"type\": \"string\"\n                    },\n                    \"content\": {\n                        \"type\": \"string\"\n                    },\n                    \"tags\": {\n                        \"type\": \"array\",\n                        \"items\": {\n                            \"type\": \"string\"\n                        }\n                    }\n                },\n                \"additionalProperties\": false\n            }\n\n+ Response 204\n"
  },
  {
    "path": "examples/Gist Fox API + Auth.md",
    "content": "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## Authentication\n*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.\n\n## Media Types\nWhere 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.\n\nRequests with a message-body are using plain JSON to set or update resource states.\n\n## Error States\nThe common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.\n\n# Gist Fox API Root [/]\nGist Fox API entry point.\n\nThis resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and\nHAL links.\n\n## Retrieve the Entry Point [GET]\n\n+ Response 200 (application/hal+json)\n    + Headers\n\n            Link: <http:/api.gistfox.com/>;rel=\"self\",<http:/api.gistfox.com/gists>;rel=\"gists\",<http:/api.gistfox.com/authorization>;rel=\"authorization\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/\" },\n                    \"gists\": { \"href\": \"/gists?{since}\", \"templated\": true },\n                    \"authorization\": { \"href\": \"/authorization\"}\n                }\n            }\n\n# Group Gist\nGist-related resources of *Gist Fox API*.\n\n## Gist [/gists/{id}{?access_token}]\nA single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note.\n\nThe Gist resource has the following attributes:\n\n+ id\n+ created_at\n+ description\n+ content\n\nThe states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation.\n\n+ Parameters\n    + id (string) - ID of the Gist in the form of a hash.\n    + access_token (string, optional) - Gist Fox API access token.\n\n+ Model (application/hal+json)\n\n    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.\n\n    + Headers\n\n            Link: <http:/api.gistfox.com/gists/42>;rel=\"self\", <http:/api.gistfox.com/gists/42/star>;rel=\"star\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/gists/42\" },\n                    \"star\": { \"href\": \"/gists/42/star\" },\n                },\n                \"id\": \"42\",\n                \"created_at\": \"2014-04-14T02:15:15Z\",\n                \"description\": \"Description of Gist\",\n                \"content\": \"String contents\"\n            }\n\n### Retrieve a Single Gist [GET]\n+ Response 200\n\n    [Gist][]\n\n### Edit a Gist [PATCH]\nTo 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.\n\n+ Request (application/json)\n\n        {\n            \"content\": \"Updated file contents\"\n        }\n\n+ Response 200\n\n    [Gist][]\n\n### Delete a Gist [DELETE]\n+ Response 204\n\n## Gists Collection [/gists{?access_token,since}]\nCollection of all Gists.\n\nThe Gist Collection resource has the following attribute:\n\n+ total\n\nIn addition it **embeds** *Gist Resources* in the Gist Fox API.\n\n+ Model (application/hal+json)\n\n    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.\n\n    + Headers\n\n            Link: <http:/api.gistfox.com/gists>;rel=\"self\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/gists\" }\n                },\n                \"_embedded\": {\n                    \"gists\": [\n                        {\n                            \"_links\" : {\n                                \"self\": { \"href\": \"/gists/42\" }\n                            },\n                            \"id\": \"42\",\n                            \"created_at\": \"2014-04-14T02:15:15Z\",\n                            \"description\": \"Description of Gist\"\n                        }\n                    ]\n                },\n                \"total\": 1\n            }\n\n### List All Gists [GET]\n+ Parameters\n    + since (string, optional) - Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.\n\n+ Response 200\n\n    [Gists Collection][]\n\n### Create a Gist [POST]\nTo create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist.\n\nThis action requires an `access_token` with `gist_write` scope.\n\n+ Parameters\n    + access_token (string, optional) - Gist Fox API access token.\n\n+ Request (application/json)\n\n        {\n            \"description\": \"Description of Gist\",\n            \"content\": \"String content\"\n        }\n\n+ Response 201\n\n    [Gist][]\n\n## Star [/gists/{id}/star{?access_token}]\nStar resource represents a Gist starred status.\n\nThe Star resource has the following attribute:\n\n+ starred\n\n+ Parameters\n    + id (string) - ID of the gist in the form of a hash\n    + access_token (string, optional) - Gist Fox API access token.\n\n+ Model (application/hal+json)\n\n    HAL+JSON representation of Star Resource.\n\n    + Headers\n\n            Link: <http:/api.gistfox.com/gists/42/star>;rel=\"self\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/gists/42/star\" },\n                },\n                \"starred\": true\n            }\n\n### Star a Gist [PUT]\nThis action requires an `access_token` with `gist_write` scope.\n\n+ Response 204\n\n### Unstar a Gist [DELETE]\nThis action requires an `access_token` with `gist_write` scope.\n\n+ Response 204\n\n### Check if a Gist is Starred [GET]\n+ Response 200\n\n    [Star][]\n\n# Group Access Authorization and Control\nAccess and Control of *Gist Fox API* OAuth token.\n\n## Authorization [/authorization]\nAuthorization Resource represents an authorization granted to the user. You can **only** access your own authorization, and only through **Basic Authentication**.\n\nThe Authorization Resource has the following attribute:\n\n+ token\n+ scopes\n\nWhere *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`.\n\n+ Model (application/hal+json)\n\n    + Headers\n\n            Link: <http:/api.gistfox.com/authorizations/1>;rel=\"self\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/authorizations\" },\n                },\n                \"scopes\": [\n                    \"gist_write\"\n                ],\n                \"token\": \"abc123\"\n            }\n\n### Retrieve Authorization [GET]\n+ Request\n    + Headers\n\n            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\n\n+ Response 200\n\n    [Authorization][]\n\n### Create Authorization [POST]\n+ Request (application/json)\n    + Headers\n\n            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\n\n    + Body\n\n            {\n                \"scopes\": [\n                    \"gist_write\"\n                ]\n            }\n\n+ Response 201\n\n        [Authorization][]\n\n### Remove an Authorization [DELETE]\n+ Request\n    + Headers\n\n            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\n\n+ Response 204\n"
  },
  {
    "path": "examples/Gist Fox API.md",
    "content": "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## Authentication\nCurrently the Gist Fox API does not provide authenticated access.\n\n## Media Types\nWhere 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.\n\nRequests with a message-body are using plain JSON to set or update resource states.\n\n## Error States\nThe common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.\n\n# Gist Fox API Root [/]\nGist Fox API entry point.\n\nThis resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and\nHAL links.\n\n## Retrieve the Entry Point [GET]\n\n+ Response 200 (application/hal+json)\n    + Headers\n\n            Link: <http:/api.gistfox.com/>;rel=\"self\",<http:/api.gistfox.com/gists>;rel=\"gists\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/\" },\n                    \"gists\": { \"href\": \"/gists?{since}\", \"templated\": true }\n                }\n            }\n\n# Group Gist\nGist-related resources of *Gist Fox API*.\n\n## Gist [/gists/{id}]\nA single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note.\n\nThe Gist resource has the following attributes:\n\n+ id\n+ created_at\n+ description\n+ content\n\nThe states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation.\n\n\n+ Parameters\n    + id (string) - ID of the Gist in the form of a hash.\n\n+ Model (application/hal+json)\n\n    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.\n\n    + Headers\n\n            Link: <http:/api.gistfox.com/gists/42>;rel=\"self\", <http:/api.gistfox.com/gists/42/star>;rel=\"star\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/gists/42\" },\n                    \"star\": { \"href\": \"/gists/42/star\" }\n                },\n                \"id\": \"42\",\n                \"created_at\": \"2014-04-14T02:15:15Z\",\n                \"description\": \"Description of Gist\",\n                \"content\": \"String contents\"\n            }\n\n### Retrieve a Single Gist [GET]\n+ Response 200\n\n    [Gist][]\n\n### Edit a Gist [PATCH]\nTo 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.\n\n+ Request (application/json)\n\n        {\n            \"content\": \"Updated file contents\"\n        }\n\n+ Response 200\n\n    [Gist][]\n\n### Delete a Gist [DELETE]\n+ Response 204\n\n## Gists Collection [/gists{?since}]\nCollection of all Gists.\n\nThe Gist Collection resource has the following attribute:\n\n+ total\n\nIn addition it **embeds** *Gist Resources* in the Gist Fox API.\n\n\n+ Model (application/hal+json)\n\n    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.\n\n    + Headers\n\n            Link: <http:/api.gistfox.com/gists>;rel=\"self\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/gists\" }\n                },\n                \"_embedded\": {\n                    \"gists\": [\n                        {\n                            \"_links\" : {\n                                \"self\": { \"href\": \"/gists/42\" }\n                            },\n                            \"id\": \"42\",\n                            \"created_at\": \"2014-04-14T02:15:15Z\",\n                            \"description\": \"Description of Gist\"\n                        }\n                    ]\n                },\n                \"total\": 1\n            }\n\n### List All Gists [GET]\n+ Parameters\n    + since (string, optional) - Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.\n\n+ Response 200\n\n    [Gists Collection][]\n\n### Create a Gist [POST]\nTo create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist.\n\n+ Request (application/json)\n\n        {\n            \"description\": \"Description of Gist\",\n            \"content\": \"String content\"\n        }\n\n+ Response 201\n\n    [Gist][]\n\n## Star [/gists/{id}/star]\nStar resource represents a Gist starred status.\n\nThe Star resource has the following attribute:\n\n+ starred\n\n\n+ Parameters\n\n    + id (string) - ID of the gist in the form of a hash\n\n+ Model (application/hal+json)\n\n    HAL+JSON representation of Star Resource.\n\n    + Headers\n\n            Link: <http:/api.gistfox.com/gists/42/star>;rel=\"self\"\n\n    + Body\n\n            {\n                \"_links\": {\n                    \"self\": { \"href\": \"/gists/42/star\" }\n                },\n                \"starred\": true\n            }\n\n### Star a Gist [PUT]\n+ Response 204\n\n### Unstar a Gist [DELETE]\n+ Response 204\n\n### Check if a Gist is Starred [GET]\n+ Response 200\n\n    [Star][]\n"
  },
  {
    "path": "examples/Polls API.md",
    "content": "FORMAT: 1A\nHOST: http://polls.apiblueprint.org/\n\n# Polls\n\nPolls 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).\n\n# Polls API Root [/]\n\nThis resource does not have any attributes. Instead it offers the initial API affordances in the form of the links in the JSON body.\n\nIt 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.\n\n## Retrieve the Entry Point [GET]\n\n+ Response 200 (application/json)\n\n        {\n            \"questions_url\": \"/questions\"\n        }\n\n## Group Question\n\nResources related to questions in the API.\n\n## Question [/questions/{question_id}]\n\nA Question object has the following attributes:\n\n+ question\n+ published_at - An ISO8601 date when the question was published.\n+ url\n+ choices - An array of Choice objects.\n\n+ Parameters\n    + question_id: 1 (required, number) - ID of the Question in form of an integer\n\n### View a Questions Detail [GET]\n\n+ Response 200 (application/json)\n\n        {\n            \"question\": \"Favourite programming language?\",\n            \"published_at\": \"2014-11-11T08:40:51.620Z\",\n            \"url\": \"/questions/1\",\n            \"choices\": [\n                {\n                    \"choice\": \"Swift\",\n                    \"url\": \"/questions/1/choices/1\",\n                    \"votes\": 2048\n                }, {\n                    \"choice\": \"Python\",\n                    \"url\": \"/questions/1/choices/2\",\n                    \"votes\": 1024\n                }, {\n                    \"choice\": \"Objective-C\",\n                    \"url\": \"/questions/1/choices/3\",\n                    \"votes\": 512\n                }, {\n                    \"choice\": \"Ruby\",\n                    \"url\": \"/questions/1/choices/4\",\n                    \"votes\": 256\n                }\n            ]\n        }\n\n## Choice [/questions/{question_id}/choices/{choice_id}]\n\n+ Parameters\n    + question_id: 1 (required, number) - ID of the Question in form of an integer\n    + choice_id: 1 (required, number) - ID of the Choice in form of an integer\n\n### Vote on a Choice [POST]\n\nThis action allows you to vote on a question's choice.\n\n+ Response 201\n\n    + Headers\n\n            Location: /questions/1\n\n## Questions Collection [/questions{?page}]\n\n+ Parameters\n    + page: 1 (optional, number) - The page of questions to return\n\n### List All Questions [GET]\n\n+ Response 200 (application/json)\n\n    + Headers\n\n            Link: </questions?page=2>; rel=\"next\"\n\n    + Body\n\n            [\n                {\n                    \"question\": \"Favourite programming language?\",\n                    \"published_at\": \"2014-11-11T08:40:51.620Z\",\n                    \"url\": \"/questions/1\",\n                    \"choices\": [\n                        {\n                            \"choice\": \"Swift\",\n                            \"url\": \"/questions/1/choices/1\",\n                            \"votes\": 2048\n                        }, {\n                            \"choice\": \"Python\",\n                            \"url\": \"/questions/1/choices/2\",\n                            \"votes\": 1024\n                        }, {\n                            \"choice\": \"Objective-C\",\n                            \"url\": \"/questions/1/choices/3\",\n                            \"votes\": 512\n                        }, {\n                            \"choice\": \"Ruby\",\n                            \"url\": \"/questions/1/choices/4\",\n                            \"votes\": 256\n                        }\n                    ]\n                }\n            ]\n\n### Create a New Question [POST]\n\nYou 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.\n\n+ question (string) - The question\n+ choices (array[string]) - A collection of choices.\n\n+ Request (application/json)\n\n        {\n            \"question\": \"Favourite programming language?\",\n            \"choices\": [\n                \"Swift\",\n                \"Python\",\n                \"Objective-C\",\n                \"Ruby\"\n            ]\n        }\n\n+ Response 201 (application/json)\n\n    + Headers\n\n            Location: /questions/2\n\n    + Body\n\n            {\n                \"question\": \"Favourite programming language?\",\n                \"published_at\": \"2014-11-11T08:40:51.620Z\",\n                \"url\": \"/questions/2\",\n                \"choices\": [\n                    {\n                        \"choice\": \"Swift\",\n                        \"url\": \"/questions/2/choices/1\",\n                        \"votes\": 0\n                    }, {\n                        \"choice\": \"Python\",\n                        \"url\": \"/questions/2/choices/2\",\n                        \"votes\": 0\n                    }, {\n                        \"choice\": \"Objective-C\",\n                        \"url\": \"/questions/2/choices/3\",\n                        \"votes\": 0\n                    }, {\n                        \"choice\": \"Ruby\",\n                        \"url\": \"/questions/2/choices/4\",\n                        \"votes\": 0\n                    }\n                ]\n            }\n\n"
  },
  {
    "path": "examples/Polls Hypermedia API.md",
    "content": "FORMAT: 1A\nHOST: http://polls.apiblueprint.org/\n\n# Polls\n\nPolls 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/).\n\n# Polls API Root [/]\n\nThis resource does not have any attributes. Instead it offers the initial API affordances.\n\n## Retrieve the Entry Point [GET]\n\n+ Response 200 (application/vnd.siren+json)\n\n        {\n            \"links\": [\n                {\n                    \"rel\": [ \"questions\" ],\n                    \"href\": \"/questions\"\n                }\n            ]\n        }\n\n+ Response 200 (application/hal+json)\n\n        {\n            \"_links\": {\n                \"questions\": { \"href\": \"/questions\" }\n            }\n        }\n\n## Questions Collection [/questions{?page}]\n\n+ Parameters\n    + page: 1 (optional, number) - The page of questions to return\n\n### List All Questions [GET]\n\n+ Relation: questions\n\n+ Response 200 (application/vnd.siren+json)\n\n        {\n            \"actions\": [\n                {\n                    \"name\": \"add\",\n                    \"href\": \"/questions\",\n                    \"method\": \"POST\",\n                    \"type\": \"application/json\",\n                    \"fields\": [\n                        {\n                            \"name\": \"question\"\n                        }, {\n                            \"name\": \"choices\"\n                        }\n                    ]\n                }\n            ],\n            \"links\": [\n                {\n                  \"rel\": [ \"next\" ],\n                  \"href\": \"/questions?page=2\"\n                },\n                {\n                  \"rel\": [ \"self\" ],\n                  \"href\": \"/questions\"\n                }\n            ],\n            \"entities\": [\n                {\n                    \"actions\": [\n                        {\n                            \"name\": \"delete\",\n                            \"href\": \"/questions/1\",\n                            \"method\": \"DELETE\"\n                        }\n                    ],\n                    \"rel\": [ \"question\" ],\n                    \"properties\": {\n                        \"published_at\": \"2014-11-11T08:40:51.620Z\",\n                        \"question\": \"Favourite programming language?\"\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1\"\n                        }\n                    ],\n                    \"entities\": [\n                        {\n                            \"actions\": [\n                                {\n                                    \"name\": \"vote\",\n                                    \"href\": \"/questions/1/choices/1\",\n                                    \"method\": \"POST\"\n                                }\n                            ],\n                            \"rel\": [ \"choice\" ],\n                            \"properties\": {\n                                \"choice\": \"Swift\",\n                                \"votes\": 2048\n                            },\n                            \"links\": [\n                                {\n                                    \"rel\": [ \"self\" ],\n                                    \"href\": \"/questions/1/choices/1\"\n                                }\n                            ]\n                        }, {\n                            \"actions\": [\n                                {\n                                    \"name\": \"vote\",\n                                    \"href\": \"/questions/1/choices/2\",\n                                    \"method\": \"POST\"\n                                }\n                            ],\n                            \"rel\": [ \"choice\" ],\n                            \"properties\": {\n                                \"choice\": \"Python\",\n                                \"votes\": 1024\n                            },\n                            \"links\": [\n                                {\n                                    \"rel\": [ \"self\" ],\n                                    \"href\": \"/questions/1/choices/2\"\n                                }\n                            ]\n                        }, {\n                            \"actions\": [\n                                {\n                                    \"name\": \"vote\",\n                                    \"href\": \"/questions/1/choices/3\",\n                                    \"method\": \"POST\"\n                                }\n                            ],\n                            \"rel\": [ \"choice\" ],\n                            \"properties\": {\n                                \"choice\": \"Objective-C\",\n                                \"votes\": 512\n                            },\n                            \"links\": [\n                                {\n                                    \"rel\": [ \"self\" ],\n                                    \"href\": \"/questions/1/choices/3\"\n                                }\n                            ]\n                        }, {\n                            \"actions\": [\n                                {\n                                    \"name\": \"vote\",\n                                    \"href\": \"/questions/1/choices/4\",\n                                    \"method\": \"POST\"\n                                }\n                            ],\n                            \"rel\": [ \"choice\" ],\n                            \"properties\": {\n                                \"choice\": \"Ruby\",\n                                \"votes\": 256\n                            },\n                            \"links\": [\n                                {\n                                    \"rel\": [ \"self\" ],\n                                    \"href\": \"/questions/1/choices/4\"\n                                }\n                            ]\n                        }\n                    ]\n                }\n            ]\n        }\n\n+ Response 200 (application/hal+json)\n\n        {\n            \"_links\": {\n                \"self\": { \"href\": \"/questions\" },\n                \"next\": { \"href\": \"/questions?page=2\" }\n            },\n            \"_embedded\": {\n                \"question\": [\n                    {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1\" }\n                        },\n                        \"_embedded\": {\n                            \"choice\": [\n                                {\n                                    \"_links\": {\n                                        \"self\": { \"self\": \"/questions/1/choices/1\" }\n                                    },\n                                    \"choice\": \"Swift\",\n                                    \"votes\": 2048\n                                }, {\n                                    \"_links\": {\n                                        \"self\": { \"self\": \"/questions/1/choices/2\" }\n                                    },\n                                    \"choice\": \"Python\",\n                                    \"votes\": 1024\n                                }, {\n                                    \"_links\": {\n                                        \"self\": { \"self\": \"/questions/1/choices/3\" }\n                                    },\n                                    \"choice\": \"Objective-C\",\n                                    \"votes\": 512\n                                }, {\n                                    \"_links\": {\n                                        \"self\": { \"self\": \"/questions/1/choices/4\" }\n                                    },\n                                    \"choice\": \"Ruby\",\n                                    \"votes\": 256\n                                }\n                            ]\n                        },\n                        \"question\": \"Favourite programming language?\",\n                        \"published_at\": \"2014-11-11T08:40:51.620Z\"\n                    }\n                ]\n            }\n        }\n\n### Create a New Question [POST]\n\nYou 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.\n\n+ question (string) - The question\n+ choices (array[string]) - A collection of choices.\n\n+ Relation: create\n\n+ Request (application/json)\n\n        {\n            \"question\": \"Favourite programming language?\",\n            \"choices\": [\n                \"Swift\",\n                \"Python\",\n                \"Objective-C\",\n                \"Ruby\"\n            ]\n        }\n\n+ Response 201 (application/vnd.siren+json)\n\n        {\n            \"actions\": [\n                {\n                    \"name\": \"delete\",\n                    \"href\": \"/questions/1\",\n                    \"method\": \"DELETE\"\n                }\n            ],\n            \"properties\": {\n                \"published_at\": \"2014-11-11T08:40:51.620Z\",\n                \"question\": \"Favourite programming language?\"\n            },\n            \"links\": [\n                {\n                    \"rel\": [ \"self\" ],\n                    \"href\": \"/questions/1\"\n                }\n            ],\n            \"entities\": [\n                {\n                    \"actions\": [\n                        {\n                            \"name\": \"vote\",\n                            \"href\": \"/questions/1/choices/1\",\n                            \"method\": \"POST\"\n                        }\n                    ],\n                    \"rel\": [ \"choices\" ],\n                    \"properties\": {\n                        \"choice\": \"Swift\",\n                        \"votes\": 2048\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1/choices/1\"\n                        }\n                    ]\n                }, {\n                    \"actions\": [\n                        {\n                            \"name\": \"vote\",\n                            \"href\": \"/questions/1/choices/2\",\n                            \"method\": \"POST\"\n                        }\n                    ],\n                    \"rel\": [ \"choices\" ],\n                    \"properties\": {\n                        \"choice\": \"Python\",\n                        \"votes\": 1024\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1/choices/2\"\n                        }\n                    ]\n                }, {\n                    \"actions\": [\n                        {\n                            \"name\": \"vote\",\n                            \"href\": \"/questions/1/choices/3\",\n                            \"method\": \"POST\"\n                        }\n                    ],\n                    \"rel\": [ \"choices\" ],\n                    \"properties\": {\n                        \"choice\": \"Objective-C\",\n                        \"votes\": 512\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1/choices/3\"\n                        }\n                    ]\n                }, {\n                    \"actions\": [\n                        {\n                            \"name\": \"vote\",\n                            \"href\": \"/questions/1/choices/4\",\n                            \"method\": \"POST\"\n                        }\n                    ],\n                    \"rel\": [ \"choices\" ],\n                    \"properties\": {\n                        \"choice\": \"Ruby\",\n                        \"votes\": 256\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1/choices/4\"\n                        }\n                    ]\n                }\n            ]\n        }\n\n+ Response 201 (application/hal+json)\n\n        {\n            \"_links\": {\n                \"self\": { \"href\": \"/questions/1\" }\n            },\n            \"_embedded\": {\n                \"choices\": [\n                    {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1/choices/1\" }\n                        },\n                        \"choice\": \"Swift\",\n                        \"votes\": 2048\n                    }, {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1/choices/2\" }\n                        },\n                        \"choice\": \"Python\",\n                        \"votes\": 1024\n                    }, {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1/choices/3\" }\n                        },\n                        \"choice\": \"Objective-C\",\n                        \"votes\": 512\n                    }, {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1/choices/4\" }\n                        },\n                        \"choice\": \"Ruby\",\n                        \"votes\": 256\n                    }\n                ]\n            },\n            \"published_at\": \"2014-11-11T08:40:51.620Z\",\n            \"question\": \"Favourite programming language?\"\n        }\n\n## Group Question\n\nResources related to questions in the API.\n\n## Question [/questions/{question_id}]\n\nA Question object has the following attributes:\n\n+ question\n+ published_at - An ISO8601 date when the question was published.\n+ url\n+ choices - An array of Choice objects.\n\n+ Parameters\n    + question_id: 1 (required, number) - ID of the Question in form of an integer\n\n### View a Questions Detail [GET]\n\n+ Relation: question\n\n+ Response 200 (application/vnd.siren+json)\n\n        {\n            \"actions\": [\n                {\n                    \"name\": \"delete\",\n                    \"href\": \"/questions/1\",\n                    \"method\": \"DELETE\"\n                }\n            ],\n            \"properties\": {\n                \"published_at\": \"2014-11-11T08:40:51.620Z\",\n                \"question\": \"Favourite programming language?\"\n            },\n            \"links\": [\n                {\n                    \"rel\": [ \"self\" ],\n                    \"href\": \"/questions/1\"\n                }\n            ],\n            \"entities\": [\n                {\n                    \"actions\": [\n                        {\n                            \"name\": \"vote\",\n                            \"href\": \"/questions/1/choices/1\",\n                            \"method\": \"POST\"\n                        }\n                    ],\n                    \"rel\": [ \"choices\" ],\n                    \"properties\": {\n                        \"choice\": \"Swift\",\n                        \"votes\": 2048\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1/choices/1\"\n                        }\n                    ]\n                }, {\n                    \"actions\": [\n                        {\n                            \"name\": \"vote\",\n                            \"href\": \"/questions/1/choices/2\",\n                            \"method\": \"POST\"\n                        }\n                    ],\n                    \"rel\": [ \"choices\" ],\n                    \"properties\": {\n                        \"choice\": \"Python\",\n                        \"votes\": 1024\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1/choices/2\"\n                        }\n                    ]\n                }, {\n                    \"actions\": [\n                        {\n                            \"name\": \"vote\",\n                            \"href\": \"/questions/1/choices/3\",\n                            \"method\": \"POST\"\n                        }\n                    ],\n                    \"rel\": [ \"choices\" ],\n                    \"properties\": {\n                        \"choice\": \"Objective-C\",\n                        \"votes\": 512\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1/choices/3\"\n                        }\n                    ]\n                }, {\n                    \"actions\": [\n                        {\n                            \"name\": \"vote\",\n                            \"href\": \"/questions/1/choices/4\",\n                            \"method\": \"POST\"\n                        }\n                    ],\n                    \"rel\": [ \"choices\" ],\n                    \"properties\": {\n                        \"choice\": \"Ruby\",\n                        \"votes\": 256\n                    },\n                    \"links\": [\n                        {\n                            \"rel\": [ \"self\" ],\n                            \"href\": \"/questions/1/choices/4\"\n                        }\n                    ]\n                }\n            ]\n        }\n\n+ Response 200 (application/hal+json)\n\n        {\n            \"_links\": {\n                \"self\": { \"href\": \"/questions/1\" }\n            },\n            \"_embedded\": {\n                \"choices\": [\n                    {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1/choices/1\" }\n                        },\n                        \"choice\": \"Swift\",\n                        \"votes\": 2048\n                    }, {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1/choices/2\" }\n                        },\n                        \"choice\": \"Python\",\n                        \"votes\": 1024\n                    }, {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1/choices/3\" }\n                        },\n                        \"choice\": \"Objective-C\",\n                        \"votes\": 512\n                    }, {\n                        \"_links\": {\n                            \"self\": { \"self\": \"/questions/1/choices/4\" }\n                        },\n                        \"choice\": \"Ruby\",\n                        \"votes\": 256\n                    }\n                ]\n            },\n            \"published_at\": \"2014-11-11T08:40:51.620Z\",\n            \"question\": \"Favourite programming language?\"\n        }\n\n## Choice [/questions/{question_id}/choices/{choice_id}]\n\n+ Parameters\n    + question_id: 1 (required, number) - ID of the Question in form of an integer\n    + choice_id: 1 (required, number) - ID of the Choice in form of an integer\n\n### View a Choice Detail [GET]\n\n+ Relation: choice\n\n+ Response 200 (application/vnd.siren+json)\n\n        {\n            \"actions\": [\n                {\n                    \"name\": \"vote\",\n                    \"href\": \"/questions/1/choices/1\",\n                    \"method\": \"POST\"\n                }\n            ],\n            \"rel\": [ \"choice\" ],\n            \"properties\": {\n                \"choice\": \"Swift\",\n                \"votes\": 2048\n            },\n            \"links\": [\n                {\n                    \"rel\": [ \"self\" ],\n                    \"href\": \"/questions/1/choices/1\"\n                }\n            ]\n        }\n\n+ Response 200 (application/hal+json)\n\n        {\n            \"_links\": {\n                \"self\": { \"href\": \"/questions/1/choices/1\" }\n            },\n            \"choice\": \"Swift\",\n            \"votes\": 2048\n        }\n\n### Vote on a Choice [POST]\n\nThis action allows you to vote on a question's choice.\n\n+ Relation: vote\n\n+ Response 201 (application/vnd.siren+json)\n\n        {\n            \"actions\": [\n                {\n                    \"name\": \"vote\",\n                    \"href\": \"/questions/1/choices/1\",\n                    \"method\": \"POST\"\n                }\n            ],\n            \"rel\": [ \"choice\" ],\n            \"properties\": {\n                \"choice\": \"Swift\",\n                \"votes\": 2049\n            },\n            \"links\": [\n                {\n                    \"rel\": [ \"self\" ],\n                    \"href\": \"/questions/1/choices/1\"\n                }\n            ]\n        }\n\n+ Response 201 (application/hal+json)\n\n        {\n            \"_links\": {\n                \"self\": \"/questions/1/choices/1\"\n            },\n            \"choice\": \"Swift\",\n            \"votes\": 2049\n        }\n"
  },
  {
    "path": "examples/README.md",
    "content": "# API Blueprint Examples\nAll files in this directory are actual **valid API blueprints**. Since they are saved with the `.md` extension GitHub automatically renders them during viewing.\n\n**To view an API blueprint source make sure to view the file as \"raw\".**\n"
  },
  {
    "path": "examples/Real World API.md",
    "content": "FORMAT: 1A\nHOST: https://alpha-api.app.net\n\n# Real World API\nThis API Blueprint demonstrates a real world example documenting a portion of\n[App.net API](http://developers.app.net).\n\nNOTE: This document is a **work in progress**.\n\n# Group Posts\nThis section groups App.net post resources.\n\n## Post [/stream/0/posts/{post_id}]\nA Post is the other central object utilized by the App.net Stream API. It has\nrich text and annotations which comprise all of the content a users sees in\ntheir feed. Posts are closely tied to the follow graph...\n\n+ Parameters\n    + post_id: `1` (string) - The id of the Post.\n\n+ Model (application/json)\n\n    ```js\n    {\n        \"data\": {\n            \"id\": \"1\", // note this is a string\n            \"user\": {\n                ...\n            },\n            \"created_at\": \"2012-07-16T17:25:47Z\",\n            \"text\": \"@berg FIRST post on this new site #newsocialnetwork\",\n            \"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>.\",\n            \"source\": {\n                \"client_id\": \"udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4\",\n                \"name\": \"Clientastic for iOS\",\n                \"link\": \"http://app.net\"\n            },\n            \"machine_only\": false,\n            \"reply_to\": null,\n            \"thread_id\": \"1\",\n            \"num_replies\": 3,\n            \"num_reposts\": 0,\n            \"num_stars\": 0,\n            \"entities\": {\n                \"mentions\": [{\n                    \"name\": \"berg\",\n                    \"id\": \"2\",\n                    \"pos\": 0,\n                    \"len\": 5\n                }],\n                \"hashtags\": [{\n                    \"name\": \"newsocialnetwork\",\n                    \"pos\": 34,\n                    \"len\": 17\n                }],\n                \"links\": [{\n                    \"text\": \"this new site\",\n                    \"url\": \"https://join.app.net\"\n                    \"pos\": 20,\n                    \"len\": 13\n                }]\n            },\n            \"you_reposted\": false,\n            \"you_starred\": false\n        },\n        \"meta\": {\n            \"code\": 200,\n        }\n    }\n    ```\n\n### Retrieve a Post [GET]\nReturns a specific Post.\n\n+ Response 200\n\n    [Post][]\n\n### Delete a Post [DELETE]\nDelete a Post. The current user must be the same user who created the Post. It\nreturns the deleted Post on success.\n\n+ Response 204\n\n## Posts Collection [/stream/0/posts]\nA Collection of posts.\n\n+ Model (application/json)\n\n    ```js\n    {\n        \"data\": [\n            {\n                \"id\": \"1\", // note this is a string\n                ...\n            },\n            {\n                \"id\": \"2\",\n                ...\n            },\n            {\n                \"id\": \"3\",\n                ...\n            },\n        ],\n        \"meta\": {\n            \"code\": 200,\n        }\n    }\n    ```\n\n### Create a Post [POST]\nCreate a new Post object. Mentions and hashtags will be parsed out of the post\ntext, as will bare URLs...\n\n+ Request\n\n    [Post][]\n\n+ Response 201\n\n    [Post][]\n\n### Retrieve all Posts [GET]\nRetrieves all posts.\n\n+ Response 200\n\n    [Posts Collection][]\n\n## Stars [/stream/0/posts/{post_id}/star]\nA User’s stars are visible to others, but they are not automatically added to\nyour followers’ streams.\n\n+ Parameters\n    + post_id: `1` (string) - The id of the Post.\n\n### Star a Post [POST]\nSave a given Post to the current User’s stars. This is just a “save” action,\nnot a sharing action.\n\n*Note: A repost cannot be starred. Please star the parent Post.*\n\n+ Response 200\n\n    [Post][]\n\n### Unstar a Post [DELETE]\nRemove a Star from a Post.\n\n+ Response 200\n\n    [Post][]\n"
  }
]