diff --git a/API Blueprint Specification.md b/API Blueprint Specification.md index f5494b1..2f17310 100644 --- a/API Blueprint Specification.md +++ b/API Blueprint Specification.md @@ -1,12 +1,12 @@ --- Author: z@apiary.io -Version: 1A7 +Version: 1A8 --- # API Blueprint -#### Format 1A revision 7 +#### Format 1A revision 8 ## [I. API Blueprint Language](#def-api-blueprint-language) 1. [Introduction](#def-introduction) @@ -27,15 +27,18 @@ Version: 1A7 4. [Headers section](#def-headers-section) 5. [Body section](#def-body-section) 6. [Schema section](#def-schema-section) -7. [Metadata section](#def-metadata-section) -8. [API name & overview section](#def-api-name-section) -9. [Resource group section](#def-resourcegroup-section) -10. [Resource section](#def-resource-section) -11. [Resource model section](#def-model-section) -12. [URI parameters section](#def-uriparameters-section) -13. [Action section](#def-action-section) -14. [Request section](#def-request-section) -15. [Response section](#def-response-section) +7. [Attributes section](#def-attributes-section) +8. [Metadata section](#def-metadata-section) +9. [API name & overview section](#def-api-name-section) +10. [Resource group section](#def-resourcegroup-section) +11. [Resource section](#def-resource-section) +12. [Resource model section](#def-model-section) +13. [URI parameters section](#def-uriparameters-section) +14. [Relation section](#def-relation-section) +15. [Action section](#def-action-section) +16. [Request section](#def-request-section) +17. [Response section](#def-response-section) +18. [Data Structures section](#def-data-structures) ## [III. Appendix](#def-appendix) 1. [URI Templates](#def-uri-templates) @@ -59,7 +62,7 @@ In addition to the regular [Markdown syntax][] API Blueprint conforms to the [Gi ## 3. API Blueprint document -An API Blueprint document – a blueprint is a plain text Markdown document describing a Web API or its part. The document is structured into logical **sections**. Each section has its distinctive meaning, content and position in the document. +An API Blueprint document – a blueprint is a plain text Markdown document describing a Web API or its part. The document is structured into logical **sections**. Each section has its distinctive meaning, content and position in the document. General section definition and structure is discussed in detail later in the [Blueprint section](#document-sections) chapter. @@ -71,22 +74,29 @@ All of the blueprint sections are optional. However, when present, a section **m + [`0-1` **API Name & overview** section](#def-api-name-section) + [`0+` **Resource** sections](#def-resource-section) + [`0-1` **URI Parameters** section](#def-uriparameters-section) + + [`0-1` **Attributes** section](#def-attributes-section) + [`0-1` **Model** section](#def-model-section) + [`0-1` **Headers** section](#def-headers-section) + [`0-1` **Body** section](#def-body-section) - + [`0-1` **Schema** section](#def-schema-section) + + [`0-1` **Schema** section](#def-schema-section) + + [`0-1` **Attributes** section](#def-attributes-section) + [`1+` **Action** sections](#def-action-section) + + [`0-1` **Relation** section](#def-relation-section) + [`0-1` **URI Parameters** section](#def-uriparameters-section) + + [`0-1` **Attributes** section](#def-attributes-section) + [`0+` **Request** sections](#def-request-section) + [`0-1` **Headers** section](#def-headers-section) + + [`0-1` **Attributes** section](#def-attributes-section) + [`0-1` **Body** section](#def-body-section) + [`0-1` **Schema** section](#def-schema-section) + [`1+` **Response** sections](#def-response-section) + [`0-1` **Headers** section](#def-headers-section) + + [`0-1` **Attributes** section](#def-attributes-section) + [`0-1` **Body** section](#def-body-section) + [`0-1` **Schema** section](#def-schema-section) + [`0+` **Resource Group** sections](#def-resourcegroup-section) + [`0+` **Resource** sections](#def-resource-section) (see above) ++ [`0+` **Data Structures** section](#def-data-structures) > **NOTE:** The number prior to a section name denotes the allowed number of the section occurrences. @@ -94,10 +104,10 @@ All of the blueprint sections are optional. However, when present, a section **m ## 4. Blueprint section -Section represents a logical unit of API Blueprint. For example an API overview, a group of resources or a resource definition. +Section represents a logical unit of API Blueprint. For example an API overview, a group of resources or a resource definition. In general a section is **defined** using a **keyword** in a Markdown entity. -Depending on the type of section the keyword is written either as a Markdown header entity or in a list item entity. +Depending on the type of section the keyword is written either as a Markdown header entity or in a list item entity. A section definition **may** also contain additional variable components such as its **identifier** and additional modifiers. @@ -105,11 +115,11 @@ A section definition **may** also contain additional variable components such as #### Example: Header-defined sections - # + # ... - # + # ... @@ -132,7 +142,7 @@ A section definition **may** also contain additional variable components such as + ... - + + ... @@ -183,6 +193,7 @@ Following reserved keywords are used in section definitions: #### Header keywords - `Group` +- `Data Structures` - [HTTP methods][httpmethods] (e.g. `GET, POST, PUT, DELETE`...) - [URI templates][uritemplate] (e.g. `/resource/{id}`) - Combinations of an HTTP method and URI Template (e.g. `GET /resource/{id}`) @@ -196,6 +207,8 @@ Following reserved keywords are used in section definitions: - `Header` & `Headers` - `Parameter` & `Parameters` - `Values` +- `Attribute` & `Attributes` +- `Relation` > **NOTE: Avoid using these keywords in other Markdown headers or lists** @@ -222,23 +235,23 @@ my-awesome-message_2 ### 4.5 Description A section description is any arbitrary Markdown-formatted content following the section definition. -It is possible to use any Markdown header or list item in a section description as long as it does not clash with any of the [reserved keywords](#def-keywords). +It is possible to use any Markdown header or list item in a section description as long as it does not clash with any of the [reserved keywords](#def-keywords). > **NOTE:** It is considered good practice to keep the header level nested under the actual section. ### 4.6 Nested sections -A section **may** contain another nested section(s). +A section **may** contain another nested section(s). -Depending on the nested section type, to nest a section simply increase its header level or its list item indentation. Anything between the section start and the start of following section at the same level is considered to be part of the section. +Depending on the nested section type, to nest a section simply increase its header level or its list item indentation. Anything between the section start and the start of following section at the same level is considered to be part of the section. What sections can be nested and where depends upon the section in case, as described in the relevant section's entry. #### Example: Nested header-defined section - #
+ #
- ... + ... ## @@ -248,7 +261,7 @@ What sections can be nested and where depends upon the section in case, as descr +
- ... + ... + @@ -339,32 +352,46 @@ Asset section is the base section for atomic data in API Blueprint. The content ## 3. Payload section - **Abstract** - **Parent sections:** vary, see descendants -- **Nested sections:** [`0-1` Headers section](#def-headers-section), [`0-1` Body section](#def-body-section), [`0-1` Schema section](#def-schema-section) +- **Nested sections:** [`0-1` Headers section](#def-headers-section), [`0-1` Attributes section](#def-attributes-section), [`0-1` Body section](#def-body-section), [`0-1` Schema section](#def-schema-section) - **Markdown entity:** list - **Inherits from**: [Named section](#def-named-section) #### Definition -Defined by a [keyword](#def-keywords) in Markdown list entity. The keyword **may** be followed by identifier. The definition **may** include payload's media-type enclosed in braces. +Defined by a [keyword](#def-keywords) in Markdown list entity. The keyword **may** be followed by identifier. The definition **may** include payload's media-type enclosed in braces. + () > **NOTE:** Refer to descendant for the particular section type definition. #### Description -Payload sections represent the information transferred as a payload of an HTTP request or response messages. A Payload consists of optional meta information in the form of HTTP headers and optional content in the form HTTP body. +Payload sections represent the information transferred as a payload of an HTTP request or response messages. A Payload consists of optional meta information in the form of HTTP headers and optional content in the form HTTP body. -Furthermore, in API Blueprint context, a payload include a description and a validation schema. +Furthermore, in API Blueprint context, a payload include its description, description of its message-body attributes and a message-body validation schema. -A payload section **may** have its media type associated. A payload's media type represents the metadata received or sent in the form of a HTTP `Content-Type` header. When specified a payload **should** include nested [Body section](#def-body-section). +A payload **may** have its media type associated. A payload's media type represents the metadata received or sent in the form of a HTTP `Content-Type` header. When specified a payload **should** include nested [Body section](#def-body-section). This section **should** include at least one following nested sections: - + - [`0-1` Headers section](#def-headers-section) +- [`0-1` Attributes section](#def-attributes-section) - [`0-1` Body section](#def-body-section) - [`0-1` Schema section](#def-schema-section) If there is no nested section the content of the payload section is considered as content of the [Body section](#def-body-section). +#### Relation of Body, Schema and Attributes sections +Each of body, schema and attributes sections describe a message payload's body. These descriptions **should** be consistent, not violating each other. When multiple body descriptions are provided they **should** be prioritized as follows: + +1. For resolving message-body schema + 1. Schema section + 2. Attributes section + 3. Body section + +2. For resolving message-body example + 1. Body section + 2. Attributes section + 3. Schema section + #### Referencing Instead of providing a payload section content a [model payload section](#def-model-section) can be referenced using the Markdown implicit [reference syntax][]: @@ -377,15 +404,15 @@ Instead of providing a payload section content a [model payload section](#def-mo This the `Payload Name` description. + Headers - + ... + Body - + ... + Schema - + ... #### Example: Referencing model payload @@ -467,8 +494,98 @@ Specifies a validation schema for the HTTP message-body of parent payload sectio --- + +## 7. Attributes Section +- **Parent sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section) | [Payload section](#def-payload-section) +- **Nested sections:** See **[Markdown Syntax for Object Notation][MSON]** +- **Markdown entity:** list +- **Inherits from**: none + +#### Definition +Defined by the `Attributes` keyword followed by an optional [MSON Type Definition][] enclosed in parentheses. + + + Attributes + +`` is the type definition of the data structure being described. If the `` is not specified, an `object` base type is assumed. See [MSON Type Definition][] for details. + +##### Example + + + Attributes (object) + +#### Description +This section describes a data structure using the **[Markdown Syntax for Object Notation][MSON] (MSON)**. Based on the parent section, the data structure being described is one of the following: + +1. Resource data structure attributes ([Resource section](#def-resource-section)) +2. Action request attributes ([Action section](#def-action-section)) +3. Payload message-body attributes ([Payload section](#def-payload-section)) + +Data structures defined in this section **may** refer to any arbitrary data structures defined in the [Data Structures section](#def-data-structures) as well as to any data structures defined by a named resource attributes description (see below). + +#### Resource Attributes description +Description of the resource data structure. + +If defined in a named [Resource section](#def-resource-section), this data structure **may** be referenced by other data structures using the resource name. + +##### Example + + # Blog Post [/posts/{id}] + Resource representing **ACME Blog** posts. + + + Attributes + + id (number) + + message (string) - The blog post article + + author: john@appleseed.com (string) - Author of the blog post + +> **NOTE:** This data structure can be later referred as: +> +> + Attributes (Blog Post) +> + +#### Action Attributes description +Description of the default request message-body data structure. + +If defined, all the [Request sections](#def-request-section) of the respective [Action section](#def-action-section) inherits these attributes unless specified otherwise. + +##### Example + + ### Create a Post [POST] + + + Attributes + + message (string) - The blog post article + + author: john@appleseed.com (string) - Author of the blog post + + + Request (application/json) + + + Request (application/yaml) + + + Response 201 + +#### Payload Attributes description +Description of payload (request, response, model) message-body attributes. + +Not every attribute has to be described. However, when an attribute is described, it **should** appear in the respective [Body section](#def-body-section) example, if a Body section is provided. + +If defined, the [Body section](#def-body-section) **may** be omitted and the example representation **should** be generated from the attributes description. + +The description of message-body attributes **may** be used to describe message-body validation if no [Schema section](#def-schema-section) is provided. When a Schema section is provided, the attributes description **should** conform to the schema. + +##### Example + + ### Retrieve a Post [GET] + + + Response 200 (application/json) + + + Attributes (object) + + message (string) - Message to the world + + + Body + + { "message" : "Hello World." } + +--- + -## 7. Metadata section +## 8. Metadata section - **Parent sections:** none - **Nested sections:** none - **Markdown entity:** special @@ -489,7 +606,7 @@ Metadata keys and its values are tool-specific. Refer to relevant tool documenta --- -## 8. API name & overview section +## 9. API name & overview section - **Parent sections:** none - **Nested sections:** none - **Markdown entity:** special, header @@ -499,7 +616,7 @@ Metadata keys and its values are tool-specific. Refer to relevant tool documenta Defined by the **first** Markdown header in the blueprint document unless it represents another section definition. #### Description -Name and description of the API +Name and description of the API #### Example @@ -509,7 +626,7 @@ Name and description of the API --- -## 9. Resource group section +## 10. Resource group section - **Parent sections:** none - **Nested sections:** [`0+` Resource section](#def-resource-section) - **Markdown entity:** header @@ -532,7 +649,7 @@ This sections represents a group of resources (Resource Sections). **May** inclu ... # Group Authors - Resources in this groups are related to **ACME Blog** authors. + Resources in this groups are related to **ACME Blog** authors. ## Resource 2 [/resource2] @@ -541,9 +658,9 @@ This sections represents a group of resources (Resource Sections). **May** inclu --- -## 10. Resource section +## 11. Resource section - **Parent sections:** none, [Resource group section](#def-resourcegroup-section) -- **Nested sections:** [`0-1` Parameters section](#def-uriparameters-section), [`0-1` Model section](#def-model-section), [`1+` Action section](#def-action-section) +- **Nested sections:** [`0-1` Parameters section](#def-uriparameters-section), [`0-1` Attributes section](#def-attributes-section), [`0-1` Model section](#def-model-section), [`1+` Action section](#def-action-section) - **Markdown entity:** header - **Inherits from**: [Named section](#def-named-section) @@ -554,13 +671,13 @@ Defined by an [URI template][uritemplate]: **-- or --** -Defined by a resource [name (identifier)](#def-identifier) followed by an URI template enclosed in square brackets `[]`. +Defined by a resource [name (identifier)](#def-identifier) followed by an [URI template][uritemplate] enclosed in square brackets `[]`. # [] **-- or --** -Defined by an [HTTP request method][httpmethods] followed by URI template: +Defined by an [HTTP request method][httpmethods] followed by [URI template][uritemplate]: # @@ -570,11 +687,16 @@ Defined by an [HTTP request method][httpmethods] followed by URI template: An API [resource](http://www.w3.org/TR/di-gloss/#def-resource) as specified by its *URI* or a set of resources (a resource template) matching its *URI template*. This section **should** include at least one nested [Action section](#def-action-section) and **may** include following nested sections: - -- [`0-1` Model section](#def-model-section) + - [`0-1` URI parameters section](#def-uriparameters-section) - URI parameters discussed in the scope of a Resource section apply to _any and all_ nested Action sections. + URI parameters defined in the scope of a Resource section apply to _any and all_ nested Action sections except when an [URI template][uritemplate] has been defined for the Action. + +- [`0-1` Attributes section][] + + Attributes defined in the scope of a Resource section represent Resource attributes. If the resource is defined with a name these attributes **may** be referenced in [Attributes sections][]. + +- [`0-1` Model section](#def-model-section) - Additional [Action sections](#def-action-section) @@ -598,7 +720,7 @@ Resource representing **ACME Blog** posts. --- -## 11. Resource model section +## 12. Resource model section - **Parent sections:** [Resource section](#def-resource-section) - **Nested sections:** [Refer to payload section](#def-payload-section) - **Markdown entity:** list @@ -618,20 +740,22 @@ The payload defined in this section **may** be referenced in any response or req #### Example # My Resource [/resource] + + Model (text/plain) - + Hello World - + ## Retrieve My Resource [GET] + + Response 200 - + [My Resource][] --- -## 12. URI parameters section +## 13. URI parameters section - **Parent Sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section) - **Nested Sections:** none - **Markdown entity:** list @@ -645,17 +769,19 @@ Defined by the `Parameters` keyword written in a Markdown list item: #### Description Discussion of URI parameters in the _scope of the parent section_. -This section **must** be composed of nested list items only. This section **must not** contain any other elements. One list item per URI parameter. The nested list items subsections inherit from the [Named section](#def-named-section) and are subject to additional formatting as follows: +This section **must** be composed of nested list items only. This section **must not** contain any other elements. Each list item describes a single URI parameter. The nested list items subsections inherit from the [Named section](#def-named-section) and are subject to additional formatting as follows: - + = `` (required | optional , , ``) ... + + : `` ( | enum[], required | optional) - - - + Values - + `` - + `` + + + Default: `` + + + Members + + `` - + + `` - ... - + `` + + `` - Where: @@ -664,13 +790,14 @@ Where: * `` is any additional **optional** Markdown-formatted [description](#SectionDescription) of the parameter. * `` is an **optional** default value of the parameter – a value that is used when no value is explicitly set (optional parameters only). * `` is an **optional** example value of the parameter (e.g. `1234`). -* `` is the **optional** parameter type as expected by the API (e.g. "number"). -* `Values` is the **optional** enumeration of possible values -* and `` represents an element of enumeration type. +* `` is the **optional** parameter type as expected by the API (e.g. "number", "string", "boolean"). "string" is the **default**. +* `Members` is the **optional** enumeration of possible values. `` should be surrounded by `enum[]` if this is present. For example, if enumeration values are present for a parameter whose type is `number`, then `enum[number]` should be used instead of `number` to. +* `` represents an element of enumeration type. +* `` is the **optional** description of the corresponding enumeration element. * `required` is the **optional** specifier of a required parameter (this is the **default**) * `optional` is the **optional** specifier of an optional parameter. -> **NOTE:** This section **should only** contain parameters that are specified in the parents' URI template, and does not have to list every URI parameter. +> **NOTE:** This section **should only** contain parameters that are specified in the parent's resource URI template, and does not have to list every URI parameter. #### Example @@ -680,41 +807,80 @@ Where: ``` + Parameters - + id ... Id of a post. + + id - Id of a post. ``` ``` + Parameters - + id (number) ... Id of a post. + + id (number) - Id of a post. ``` ``` + Parameters - + id (required, number, `1001`) ... Id of a post. + + id: `1001` (number, required) - Id of a post. ``` ``` + Parameters - + id = `20` (optional, number, `1001`) ... Id of a post. + + id: `1001` (number, optional) - Id of a post. + + Default: `20` ``` ``` + Parameters - + id (string) + + id (enum[string]) Id of a Post - + Values - + `A` + + Members + + `A` - This is character A + `B` - + `C` + + `C` - This is character C ``` --- + +## 14. Relation section +- **Parent sections:** [Action section](#def-action-section) +- **Nested Sections:** none +- **Markdown entity:** list +- **Inherits from**: none + +#### Definition +Defined by the `Relation` keyword written in a Markdown list item followed by a colon (`:`) and a link relation identifier. + + + Relation: + +#### Description +This section specifies a [link relation type](https://tools.ietf.org/html/rfc5988#section-4) for the given action as specified by [RFC 5988](https://tools.ietf.org/html/rfc5988). + +> **NOTE:** The link relation identifiers should be unique per resource in the blueprint document. + +#### Example + + # Task [/tasks/{id}] + + + Parameters + + id + + ## Retrieve Task [GET] + + + Relation: task + + Response 200 + + { ... } + + ## Delete Task [DELETE] + + + Relation: delete + + Response 204 + +--- + -## 13. Action section +## 15. Action section - **Parent sections:** [Resource section](#def-resource-section) -- **Nested sections:** [`0-1` URI parameters section](#def-uriparameters-section), [`0+` Request section](#def-request-section), [`1+` Response section](#def-response-section) +- **Nested sections:** [`0-1` Relation section](#def-relation-section), [`0-1` URI parameters section](#def-uriparameters-section), [`0-1` Attributes section](#def-attributes-section), [`0+` Request section](#def-request-section), [`1+` Response section](#def-response-section) - **Markdown entity:** header - **Inherits from**: [Named section](#def-named-section) @@ -727,14 +893,22 @@ Defined by an [HTTP request method][httpmethods]: Defined by an action [name (identifier)](#def-identifier) followed by an [HTTP request method][httpmethods] enclosed in square brackets `[]`. - # [] + ## [] + +**-- or --** + +Defined by an action [name (identifier)](#def-identifier) followed by an [HTTP request method][httpmethods] and [URI template][uritemplate] enclosed in square brackets `[]`. + + ## [ ] #### Description Definition of at least one complete HTTP transaction as performed with the parent resource section. An action section **may** consists of multiple HTTP transaction examples for the given HTTP request method. This section **may** include one nested [URI parameters section](#def-uriparameters-section) describing any URI parameters _specific_ to the action – URI parameters discussed in the scope of an Action section apply to the respective Action section ONLY. -It **should** include at least one nested [Response section](#def-response-section) and **may** include additional nested [Request](#def-request-section) and [Response](#def-response-section) sections. +This section **may** include one nested [Attributes section][] defining the input (request) attributes of the section. If present, these attributes **should** be inherited in every Action's [Request section][] unless specified otherwise. + +Action section **should** include at least one nested [Response section](#def-response-section) and **may** include additional nested [Request](#def-request-section) and [Response](#def-response-section) sections. Nested Request and Response sections **may** be ordered into groups where each groups represent one transaction example. First transaction example group starts with the first nested Request or Response section. Subsequent groups start with the first nested Request section following a Response section. @@ -743,11 +917,11 @@ Multiple Request and Response nested sections within one transaction example **s #### Example # Blog Posts [/posts{?limit}] - ... + ... ## Retrieve Blog Posts [GET] Retrieves the list of **ACME Blog** posts. - + + Parameters + limit (optional, number) ... Maximum number of posts to retrieve @@ -756,6 +930,11 @@ Multiple Request and Response nested sections within one transaction example **s ... ### Create a Post [POST] + + + Attributes + + ... + + Request ... @@ -764,41 +943,48 @@ Multiple Request and Response nested sections within one transaction example **s ... + ### Delete a Post [DELETE /posts/{id}] + + + Parameters + + id (string) ... Id of the post + + + Response 204 + #### Example Multiple Transaction Examples # Resource [/resource] ## Create Resource [POST] + request A - + ... + response 200 - + ... + request B - + ... - + response 200 - + + response 200 + ... + response 500 - + ... + request C - + ... + request D - + ... + response 200 - + ... > **NOTE:** The "Multiple Transaction Examples" example demonstrates three transaction examples for one given action: @@ -810,7 +996,7 @@ Multiple Request and Response nested sections within one transaction example **s --- -## 14. Request section +## 16. Request section - **Parent sections:** [Action section](#def-action-section) - **Nested sections:** [Refer to payload section](#def-payload-section) - **Markdown entity:** list @@ -827,13 +1013,13 @@ One HTTP request-message example – payload. #### Example + Request Create Blog Post (application/json) - + { "message" : "Hello World." } --- -## 15. Response section +## 17. Response section - **Abstract** - **Parent sections:** [Action section](#def-action-section) - **Nested sections:** [Refer to payload section](#def-payload-section) @@ -851,11 +1037,72 @@ One HTTP response-message example – payload. #### Example + Response 201 (application/json) - + { "message" : "created" } --- + +## 18. Data Structures section +- **Parent sections:** none +- **Nested sections:** _MSON Named Type definition_ (see below) +- **Markdown entity:** header +- **Inherits from**: none + +#### Definition +Defined by the `Data Structures` keyword. + + # Data Structures + +#### Description +This section holds arbitrary data structures definitions defined in the form of [MSON Named Types][]. + +Data structures defined in this section **may** be used in any [Attributes section][]. Similarly, any data structures defined in a [Attributes section][] of a named [Resource Section][] **may** be used in a data structure definition. + +Refer to the [MSON][] specification for full details on how to define an MSON Named type. + +#### Example + + # Data Structures + + ## Message (object) + + + text (string) - text of the message + + author (Author) - author of the message + + ## Author (object) + + + name: John + + email: john@appleseed.com + + +#### Example reusing Data Structure in Resource + + # User [/user] + + + Attributes (Author) + + # Data Structures + + ## Author (object) + + + name: John + + email: john@appleseed.com + +#### Example reusing Resource-defined Data Structure + + # User [/user] + + + Attributes + + name: John + + email: john@appleseed.com + + # Data Structures + + ## Author (User) + +--- +
@@ -881,16 +1128,16 @@ Variable names are case-sensitive. The variable name may consists of following c - ASCII alpha numeric characters (`a-z`, `A-Z`) - Decimal digits (`0-9`) - `_` -- [Percent-encoded][pct-encoded] characters +- [Percent-encoded][pct-encoded] characters - `.` -Multiple variables are separated by the comma **without** any leading or trailing spaces. A variable(s) **must** be enclosed in braces – `{}` **without** any additional leading or trailing whitespace. +Multiple variables are separated by the comma **without** any leading or trailing spaces. A variable(s) **must** be enclosed in braces – `{}` **without** any additional leading or trailing whitespace. #### Operators The first variable in the braces **might** be preceded by an operator. API Blueprint currently supports following operators: -- `#` – _fragment identifier_ operator +- `#` – _fragment identifier_ operator - `+` – _reserved value_ operator - `?` – _form-style query_ operator - `&` – _form-style query continuation_ operator @@ -930,7 +1177,7 @@ With `var := 42` the expansion is `/path/to/resources/42`. ### Fragment Identifier Variable -URI Template variables for fragment identifiers are defined using the crosshatch (`#`) operator: +URI Template variables for fragment identifiers are defined using the crosshatch (`#`) operator: ``` /path/to/resources/42{#var} @@ -962,7 +1209,7 @@ To define variables for a form-style query use the question mark (`?`) operator With `varone := 42` and `vartwo = hello` the expansion is `/path/to/resources/42?vartwo=hello`. -To continue a form-style query use the ampersand (`&`) operator: +To continue a form-style query use the ampersand (`&`) operator: ``` /path/to/resources/{varone}?path=test{&vartwo,varthree} @@ -986,3 +1233,15 @@ With `varone := 42`, `vartwo = hello`, `varthree = 1024` the expansion is `/path [list syntax]: https://daringfireball.net/projects/markdown/syntax#list [pct-encoded]: http://en.wikipedia.org/wiki/Percent-encoding [uri-explode]: http://tools.ietf.org/html/rfc6570#section-2.4.2 + +[MSON]: https://github.com/apiaryio/mson +[MSON Named Types]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#22-named-types +[MSON Type Definition]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#35-type-definition + +[`0-1` Attributes section]: #def-attributes-section +[Attributes section]: #def-attributes-section +[Attributes sections]: #def-attributes-section + +[Resource Section]: #def-resource-section + +[Request section]: #def-request-section diff --git a/Glossary of Terms.md b/Glossary of Terms.md index f1babfe..acf47d7 100644 --- a/Glossary of Terms.md +++ b/Glossary of Terms.md @@ -22,10 +22,18 @@ The **API Blueprint language**. A format used to describe API in an API blueprin ### Asset **Atomic data**. Most often representing one resource representation in the form of message-body or its validation schema. + +### Attribute +Based on the context, attribute (property) of a message-body data structure, or attribute of a resource, or an input attribute of a transition – [Action](#def-action). + ### Blueprint An **API description**. A **blueprint file** (or a set of files) that describes an API using the API Blueprint language. + +### Data Structure +A particular data organization, or a description of it. In API Blueprint, data structures and its [Attributes](#def-attribute) are described using the Markdown Syntax for Object Notation – [MSON][]. + ### Entity [**Entity**](http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html) being transferred in a [payload](#def-payload). @@ -100,3 +108,9 @@ A compact sequence of characters for describing a range of **Uniform Resource Id + [HTTP/1.1 Terminology](http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html#sec1.3) + [W3C Glossary of Terms for Device Independence](http://www.w3.org/TR/di-gloss) + [Know your HTTP well](https://github.com/for-GET/know-your-http-well) ++ [Markdown Syntax for Object Notation][MSON] + + + +[MSON]: https://github.com/apiaryio/mson + diff --git a/README.md b/README.md index 571fea2..9840d1f 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,11 @@ API Blueprint, its parser, and most of its tools are completely open sourced so + Understandable by machines + Open & free +## Format support + +* Current format: [1A8](https://github.com/apiaryio/api-blueprint/releases/tag/format-1A8) +* Format supported by Apiary: [1A7](https://github.com/apiaryio/api-blueprint/releases/tag/format-1A7) + ## Getting started with API Blueprint All it takes to describe that `message` endpoint of your API is to write: @@ -55,7 +60,7 @@ Building tools for API Blueprint is possible thanks to its machine-friendly face \[[full listing](https://github.com/apiaryio/api-blueprint-ast#json-serialization)\] -It is the task for the API Blueprint parser – [Snow Crash][] or one of its language bindings to translate the API Blueprint Markdown representation into a machine friendly format – AST. +It is the task for the API Blueprint parser – [Drafter][] or one of its language bindings to translate the API Blueprint Markdown representation into a machine friendly format – AST. If you are interested in building tools for API Blueprint or just to integrate it with your workflow check out the [Developing tools for API Blueprint](https://github.com/apiaryio/api-blueprint/wiki/Developing-tools-for-API-Blueprint). @@ -66,13 +71,13 @@ The media type for API Blueprint is `text/vnd.apiblueprint+markdown`. + [Tutorial](Tutorial.md) + [Examples](examples) + [Glossary of Terms](Glossary%20of%20Terms.md) -+ [API Blueprint Map](https://github.com/apiaryio/api-blueprint/wiki/API-Blueprint-Map) ++ [API Blueprint Map](assets/map.png) + [Language Specification](API%20Blueprint%20Specification.md) + [Tools working with API Blueprint](http://apiblueprint.org/#tooling) ### Developers -+ [API Blueprint reference parser – Snow Crash](https://github.com/apiaryio/snowcrash) -+ [Snow Crash Bindings to other languages](https://github.com/apiaryio/snowcrash#bindings) ++ [API Blueprint reference parser – Drafter](https://github.com/apiaryio/drafter) ++ [Drafter Bindings to other languages](https://github.com/apiaryio/drafter#bindings) + [API Blueprint AST Serialization Media Types](https://github.com/apiaryio/api-blueprint-ast) + [Developing tools for API Blueprint](https://github.com/apiaryio/api-blueprint/wiki/Developing-tools-for-API-Blueprint) @@ -88,4 +93,4 @@ Ask at [Stack Overflow](http://stackoverflow.com/questions/tagged/apiblueprint), ## License MIT License. See the [LICENSE](https://github.com/apiaryio/api-blueprint/blob/master/LICENSE) file. -[Snow Crash]: https://github.com/apiaryio/snowcrash +[Drafter]: https://github.com/apiaryio/drafter diff --git a/assets/map.png b/assets/map.png index e364701..088745b 100644 Binary files a/assets/map.png and b/assets/map.png differ diff --git a/examples/1. Simplest API.md b/examples/01. Simplest API.md similarity index 57% rename from examples/1. Simplest API.md rename to examples/01. Simplest API.md index 08a0947..6056ef5 100644 --- a/examples/1. Simplest API.md +++ b/examples/01. Simplest API.md @@ -2,15 +2,15 @@ FORMAT: 1A # The Simplest API This is one of the simplest APIs written in the **API Blueprint**. -One plain resource combined with a method and that's it! We will explain what is going on in the next installment - [Resource and Actions](2.%20Resource%20and%20Actions.md). +One plain resource combined with a method and that's it! We will explain what is going on in the next installment - [Resource and Actions](02.%20Resource%20and%20Actions.md). -**Note:** As we progress through the examples, do not also forget to view the [Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/1.%20Simplest%20API.md) code to see what is really going on in the API Blueprint, as opposed to just seeing the output of the Github Markdown parser. +**Note:** As we progress through the examples, do not also forget to view the [Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md) code to see what is really going on in the API Blueprint, as opposed to just seeing the output of the Github Markdown parser. -Also please keep in mind that every single example in this course is a **real API Blueprint** and as such you can **parse** it with the [API Blueprint parser](https://github.com/apiaryio/snowcrash) or one of its [bindings](https://github.com/apiaryio/snowcrash#bindings). +Also please keep in mind that every single example in this course is a **real API Blueprint** and as such you can **parse** it with the [API Blueprint parser](https://github.com/apiaryio/drafter) or one of its [bindings](https://github.com/apiaryio/drafter#bindings). ## API Blueprint -+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/1.%20Simplest%20API.md) -+ [Next: Resource and Actions](2.%20Resource%20and%20Actions.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md) ++ [Next: Resource and Actions](02.%20Resource%20and%20Actions.md) # GET /message + Response 200 (text/plain) diff --git a/examples/2. Resource and Actions.md b/examples/02. Resource and Actions.md similarity index 88% rename from examples/2. Resource and Actions.md rename to examples/02. Resource and Actions.md index 65c662a..a26cfa6 100644 --- a/examples/2. Resource and Actions.md +++ b/examples/02. Resource and Actions.md @@ -4,9 +4,9 @@ FORMAT: 1A This API example demonstrates how to define a resource with multiple actions. ## API Blueprint -+ [Previous: The Simplest API](1.%20Simplest%20API.md) -+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/2.%20Resource%20and%20Actions.md) -+ [Next: Named Resource and Actions](3.%20Named%20Resource%20and%20Actions.md) ++ [Previous: The Simplest API](01.%20Simplest%20API.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/02.%20Resource%20and%20Actions.md) ++ [Next: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md) # /message This is our [resource](http://www.w3.org/TR/di-gloss/#def-resource). It is defined by its [URI](http://www.w3.org/TR/di-gloss/#def-uniform-resource-identifier) or, more precisely, by its [URI Template](http://tools.ietf.org/html/rfc6570). diff --git a/examples/3. Named Resource and Actions.md b/examples/03. Named Resource and Actions.md similarity index 80% rename from examples/3. Named Resource and Actions.md rename to examples/03. Named Resource and Actions.md index 0691f6b..2883d1d 100644 --- a/examples/3. Named Resource and Actions.md +++ b/examples/03. Named Resource and Actions.md @@ -4,9 +4,9 @@ FORMAT: 1A This API example demonstrates how to name a resource and its actions, to give the reader a better idea about what the resource is used for. ## API Blueprint -+ [Previous: Resource and Actions](2.%20Resource%20and%20Actions.md) -+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/3.%20Named%20Resource%20and%20Actions.md) -+ [Next: Grouping Resources](4.%20Grouping%20Resources.md) ++ [Previous: Resource and Actions](02.%20Resource%20and%20Actions.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/03.%20Named%20Resource%20and%20Actions.md) ++ [Next: Grouping Resources](04.%20Grouping%20Resources.md) # My Message [/message] OK, `My Message` probably isn't the best name for our resource but it will do for now. Note the URI `/message` is enclosed in square brackets. diff --git a/examples/4. Grouping Resources.md b/examples/04. Grouping Resources.md similarity index 86% rename from examples/4. Grouping Resources.md rename to examples/04. Grouping Resources.md index 6ba3eee..35fd305 100644 --- a/examples/4. Grouping Resources.md +++ b/examples/04. Grouping Resources.md @@ -4,9 +4,9 @@ FORMAT: 1A This API example demonstrates how to group resources and form **groups of resources**. You can create as many or as few groups as you like. If you do not create any group all your resources will be part of an "unnamed" group. ## API Blueprint -+ [Previous: Named Resource and Actions](3.%20Named%20Resource%20and%20Actions.md) -+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/4.%20Grouping%20Resources.md) -+ [Next: Responses](5.%20Responses.md) ++ [Previous: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/04.%20Grouping%20Resources.md) ++ [Next: Responses](05.%20Responses.md) # Group Messages Group of all messages-related resources. diff --git a/examples/5. Responses.md b/examples/05. Responses.md similarity index 89% rename from examples/5. Responses.md rename to examples/05. Responses.md index 0c3d2c6..825a2ef 100644 --- a/examples/5. Responses.md +++ b/examples/05. Responses.md @@ -4,9 +4,9 @@ FORMAT: 1A In this API example we will discuss what information a response can bear and how to define multiple responses. Technically a response is represented by a payload that is sent back in response to a request. ## API Blueprint -+ [Previous: Grouping Resources](4.%20Grouping%20Resources.md) -+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/5.%20Responses.md) -+ [Next: Requests](6.%20Requests.md) ++ [Previous: Grouping Resources](04.%20Grouping%20Resources.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/05.%20Responses.md) ++ [Next: Requests](06.%20Requests.md) # Group Messages Group of all messages-related resources. diff --git a/examples/6. Requests.md b/examples/06. Requests.md similarity index 77% rename from examples/6. Requests.md rename to examples/06. Requests.md index c955ca6..7ad6191 100644 --- a/examples/6. Requests.md +++ b/examples/06. Requests.md @@ -1,12 +1,12 @@ FORMAT: 1A # Requests API -Following the [Responses](5.%20Responses.md) example, this API will show you how to define multiple requests and what data these requests can bear. Let's demonstrate multiple requests on a trivial example of content negotiation. +Following the [Responses](05.%20Responses.md) example, this API will show you how to define multiple requests and what data these requests can bear. Let's demonstrate multiple requests on a trivial example of content negotiation. ## API Blueprint -+ [Previous: Responses](5.%20Responses.md) -+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/6.%20Requests.md) -+ [Next: Parameters](7.%20Parameters.md) ++ [Previous: Responses](05.%20Responses.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/06.%20Requests.md) ++ [Next: Parameters](07.%20Parameters.md) # Group Messages Group of all messages-related resources. diff --git a/examples/7. Parameters.md b/examples/07. Parameters.md similarity index 88% rename from examples/7. Parameters.md rename to examples/07. Parameters.md index bdd7494..b937820 100644 --- a/examples/7. Parameters.md +++ b/examples/07. Parameters.md @@ -1,14 +1,14 @@ FORMAT: 1A # Parameters API -In this installment of the API Blueprint course we will discuss how to describe API parameters. +In this installment of the API Blueprint course we will discuss how to describe URI parameters. But first let's add more messages to our system. For that we would need introduce an message identifier – id. This id will be our parameter when communicating with our API about messages. ## API Blueprint -+ [Previous: Requests](6.%20Requests.md) -+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/7.%20Parameters.md) -+ [Next: Resource Model](8.%20Resource%20Model.md) ++ [Previous: Requests](06.%20Requests.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/07.%20Parameters.md) ++ [Next: Attributes](08.%20Attributes.md) # Group Messages Group of all messages-related resources. @@ -19,7 +19,7 @@ Note the parameter name `id` is enclosed in curly brackets. We will discuss this + Parameters - + id (number, `1`) ... An unique identifier of the message. + + id: 1 (number) - An unique identifier of the message. ### Retrieve a Message [GET] @@ -79,7 +79,8 @@ We have added the query URI template parameter - `limit`. This parameter is used + Parameters - + limit = `20` (optional, number) ... The maximum number of results to return. + + limit (number, optional) - The maximum number of results to return. + + Default: `20` + Response 200 (application/json) diff --git a/examples/08. Attributes.md b/examples/08. Attributes.md new file mode 100644 index 0000000..ce143f7 --- /dev/null +++ b/examples/08. Attributes.md @@ -0,0 +1,39 @@ +FORMAT: 1A + +# Attributes API +This API example demonstrates how to describe body attributes of a request or response message. + +In this case, the description is complementary (and duplicate!) to the provided JSON example in the body section. The [Advanced Attributes](09.%20Advanced%20Attributes.md) API example will demonstrate how to avoid duplicates and how to reuse attributes descriptions. + +## API Blueprint ++ [Previous: Parameters](07.%20Parameters.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/08.%20Attributes.md) ++ [Next: Advanced Attributes](09.%20Advanced%20Attributes.md) + +# Group Coupons + +## Coupon [/coupons/{id}] +A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. + +### Retrieve a Coupon [GET] +Retrieves the coupon with the given ID. + ++ Response 200 (application/json) + + + Attributes (object) + + id: 250FF (string) + + created: 1415203908 (number) - Time stamp + + percent_off: 25 (number) + + A positive integer between 1 and 100 that represents the discount the coupon will apply. + + + redeem_by (number) - Date after which the coupon can no longer be redeemed + + + Body + + { + "id": "250FF", + "created": 1415203908, + "percent_off": 25, + "redeem_by:" null + } diff --git a/examples/09. Advanced Attributes.md b/examples/09. Advanced Attributes.md new file mode 100644 index 0000000..fd3cd2f --- /dev/null +++ b/examples/09. Advanced Attributes.md @@ -0,0 +1,69 @@ +FORMAT: 1A + +# Advanced Attributes API +Improving the previous [Attributes](08.%20Attributes.md) description example, this API example describes the `Coupon` resource attributes (data structure) regardless of the serialization format. These attributes can be later referenced using the resource name + +These attributes are then reused in the `Retrieve a Coupon` action. Since they describe the complete message, no explicit JSON body example is needed. + +Moving forward, the `Coupon` resource data structure is then reused when defining the attributes of the coupons collection resource – `Coupons`. + +The `Create a Coupon` action also demonstrate the description of request attributes – once defined, these attributes are implied on every `Create a Coupon` request unless the request specifies otherwise. Apparently, the description of action attributes is somewhat duplicate to the definition of `Coupon` resource attributes. We will address this in the next [Data Structures](10.%20Data%20Structures.md) example. + +## API Blueprint ++ [Previous: Attributes](08.%20Attributes.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/09.%20Advanced%20Attributes.md) ++ [Next: Data Structures](10.%20Data%20Structures.md) + +# Group Coupons + +## Coupon [/coupons/{id}] +A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. + ++ Parameters + + id (string) + + The ID of the desired coupon. + ++ Attributes (object) + + id: 250FF (string) + + created: 1415203908 (number) - Time stamp + + percent_off: 25 (number) + + A positive integer between 1 and 100 that represents the discount the coupon will apply. + + + redeem_by (number) - Date after which the coupon can no longer be redeemed + +### Retrieve a Coupon [GET] +Retrieves the coupon with the given ID. + ++ Response 200 (application/json) + + Attributes (Coupon) + +## Coupons [/coupons{?limit}] + ++ Attributes (array[Coupon]) + +### List all Coupons [GET] +Returns a list of your coupons. + ++ Parameters + + limit (number, optional) + + A limit on the number of objects to be returned. Limit can range between 1 and 100 items. + + + Default: `10` + ++ Response 200 (application/json) + + Attributes (Coupons) + +### Create a Coupon [POST] +Creates a new Coupon. + ++ Attributes (object) + + percent_off: 25 (number) + + redeem_by (number) + ++ Request (application/json) + ++ Response 200 (application/json) + + Attributes (Coupon) diff --git a/examples/10. Data Structures.md b/examples/10. Data Structures.md new file mode 100644 index 0000000..efc13a0 --- /dev/null +++ b/examples/10. Data Structures.md @@ -0,0 +1,67 @@ +FORMAT: 1A + +# Data Structures API +Following [Advanced Attributes](09.%20Advanced%20Attributes.md), this example demonstrates defining arbitrary data structure to be reused by various attribute descriptions. + +Since a portion of the `Coupon` data structure is shared between the `Coupon` definition itself and the `Create a Coupon` action, it was separated into a `Coupon Base` data structure in the `Data Strucutes` API Blueprint Section. Doing so enables us to reuse it as a base-type of other attribute definitions. + +## API Blueprint ++ [Previous: Advanced Attributes](09.%20Advanced%20Attributes.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/10.%20Data%20Structures.md) ++ [Next: Resource Model](11.%20Resource%20Model.md) + +# Group Coupons + +## Coupon [/coupons/{id}] +A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. + ++ Parameters + + id (string) + + The ID of the desired coupon. + ++ Attributes (Coupon Base) + + id: 250FF (string) + + created: 1415203908 (number) - Time stamp + +### Retrieve a Coupon [GET] +Retrieves the coupon with the given ID. + ++ Response 200 (application/json) + + Attributes (Coupon) + +## Coupons [/coupons{?limit}] + ++ Attributes (array[Coupon]) + +### List all Coupons [GET] +Returns a list of your coupons. + ++ Parameters + + limit (number, optional) + + A limit on the number of objects to be returned. Limit can range between 1 and 100 items. + + + Default: `10` + ++ Response 200 (application/json) + + Attributes (Coupons) + +### Create a Coupon [POST] +Creates a new Coupon. + ++ Attributes (Coupon Base) + ++ Request (application/json) + ++ Response 200 (application/json) + + Attributes (Coupon) + +# Data Structures + +## Coupon Base (object) ++ percent_off: 25 (number) + + A positive integer between 1 and 100 that represents the discount the coupon will apply. + ++ redeem_by (number) - Date after which the coupon can no longer be redeemed diff --git a/examples/8. Resource Model.md b/examples/11. Resource Model.md similarity index 78% rename from examples/8. Resource Model.md rename to examples/11. Resource Model.md index bd394d1..ba1c904 100644 --- a/examples/8. Resource Model.md +++ b/examples/11. Resource Model.md @@ -3,11 +3,12 @@ FORMAT: 1A # Resource Model API Resource model is a [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation). One particular representation of your resource. -Furthermore, in API Blueprint, any `resource model` you have defined can be referenced in a request or response section, saving you lots of time maintaining your API blueprint. You simply define a resource model as any payload (e. g. [request](https://github.com/apiaryio/api-blueprint/blob/master/examples/6.%20Requests.md) or [response](https://github.com/apiaryio/api-blueprint/blob/master/examples/5.%20Responses.md)) and then reference it later where you would normally write a `request` or `response`. +Furthermore, in API Blueprint, any `resource model` you have defined can be referenced in a request or response section, saving you lots of time maintaining your API blueprint. You simply define a resource model as any payload (e. g. [request](https://github.com/apiaryio/api-blueprint/blob/master/examples/06.%20Requests.md) or [response](https://github.com/apiaryio/api-blueprint/blob/master/examples/5.%20Responses.md)) and then reference it later where you would normally write a `request` or `response`. ## API Blueprint -+ [Previous: Parameters](7.%20Parameters.md) -+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/8.%20Resource%20Model.md) ++ [Previous: Data Structures](10.%20Data%20Structures.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/10.%20Resource%20Model.md) ++ [Next: Advanced Action](12.%20Advanced%20Action.md) # Group Messages Group of all messages-related resources. diff --git a/examples/12. Advanced Action.md b/examples/12. Advanced Action.md new file mode 100644 index 0000000..f94dc67 --- /dev/null +++ b/examples/12. Advanced Action.md @@ -0,0 +1,55 @@ +FORMAT: 1A + +# Advanced Action API +A resource action is – in fact – a state transition. This API example demonstrates an action - state transition - to another resource. + +## API Blueprint ++ [Previous: Resource Model](11.%20Resource%20Model.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/11.%20Advanced%20Action.md) + +# Tasks [/tasks/tasks{?status,priority}] + ++ Parameters + + status (string) + + priority (number) + +## List All Tasks [GET] + ++ Response 200 (application/json) + + [ + { + "id": 123, + "name": "Exercise in gym", + "done": false, + "type": "task" + }, + { + "id": 124, + "name": "Shop for groceries", + "done": true, + "type": "task" + } + ] + +## Retrieve Task [GET /task/{id}] +This is a state transition to another resource + ++ Parameters + + id (string) + ++ Response 200 (application/json) + + { + "id": 123, + "name": "Go to gym", + "done": false, + "type": "task" + } + +## Delete Task [DELETE /task/{id}] + ++ Parameters + + id (string) + ++ Response 204 diff --git a/examples/Gist Fox API + Auth.md b/examples/Gist Fox API + Auth.md index 6ba8cef..2547f94 100644 --- a/examples/Gist Fox API + Auth.md +++ b/examples/Gist Fox API + Auth.md @@ -53,8 +53,8 @@ The Gist resource has the following attributes: The states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation. + Parameters - + id (string) ... ID of the Gist in the form of a hash. - + access_token (string, optional) ... Gist Fox API access token. + + id (string) - ID of the Gist in the form of a hash. + + access_token (string, optional) - Gist Fox API access token. + Model (application/hal+json) @@ -138,7 +138,7 @@ In addition it **embeds** *Gist Resources* in the Gist Fox API. ### List All Gists [GET] + Parameters - + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned. + + since (string, optional) - Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned. + Response 200 @@ -150,7 +150,7 @@ To create a new Gist simply provide a JSON hash of the *description* and *conten This action requires an `access_token` with `gist_write` scope. + Parameters - + access_token (string, optional) ... Gist Fox API access token. + + access_token (string, optional) - Gist Fox API access token. + Request (application/json) @@ -171,8 +171,8 @@ The Star resource has the following attribute: + starred + Parameters - + id (string) ... ID of the gist in the form of a hash - + access_token (string, optional) ... Gist Fox API access token. + + id (string) - ID of the gist in the form of a hash + + access_token (string, optional) - Gist Fox API access token. + Model (application/hal+json) diff --git a/examples/Gist Fox API.md b/examples/Gist Fox API.md index 2d04689..0e7aca2 100644 --- a/examples/Gist Fox API.md +++ b/examples/Gist Fox API.md @@ -53,7 +53,7 @@ The states *id* and *created_at* are assigned by the Gist Fox API at the moment + Parameters - + id (string) ... ID of the Gist in the form of a hash. + + id (string) - ID of the Gist in the form of a hash. + Model (application/hal+json) @@ -138,7 +138,7 @@ In addition it **embeds** *Gist Resources* in the Gist Fox API. ### List All Gists [GET] + Parameters - + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned. + + since (string, optional) - Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned. + Response 200 @@ -168,7 +168,7 @@ The Star resource has the following attribute: + Parameters - + id (string) ... ID of the gist in the form of a hash + + id (string) - ID of the gist in the form of a hash + Model (application/hal+json) diff --git a/examples/Polls Hypermedia API.md b/examples/Polls Hypermedia API.md index 471d76e..38e4ca2 100644 --- a/examples/Polls Hypermedia API.md +++ b/examples/Polls Hypermedia API.md @@ -37,6 +37,8 @@ This resource does not have any attributes. Instead it offers the initial API af ### List All Questions [GET] ++ Relation: questions + + Response 200 (application/vnd.siren+json) { @@ -224,6 +226,8 @@ You may create your own question using this action. It takes a JSON object conta + question (string) - The question + choices (array[string]) - A collection of choices. ++ Relation: create + + Request (application/json) { @@ -394,6 +398,8 @@ A Question object has the following attributes: ### View a Questions Detail [GET] ++ Relation: question + + Response 200 (application/vnd.siren+json) { @@ -542,6 +548,8 @@ A Question object has the following attributes: ### View a Choice Detail [GET] ++ Relation: choice + + Response 200 (application/vnd.siren+json) { @@ -579,6 +587,8 @@ A Question object has the following attributes: This action allows you to vote on a question's choice. ++ Relation: vote + + Response 201 (application/vnd.siren+json) { diff --git a/examples/Real World API.md b/examples/Real World API.md index 50564ee..ff03c75 100644 --- a/examples/Real World API.md +++ b/examples/Real World API.md @@ -13,7 +13,7 @@ This section groups App.net post resources. A Post is the other central object utilized by the App.net Stream API. It has rich text and annotations which comprise all of the content a users sees in their feed. Posts are closely tied to the follow graph... + Parameters - + post_id (string, `1`) ... The id of the Post. + + post_id: `1` (string) - The id of the Post. + Model (application/json) @@ -127,7 +127,7 @@ Retrieves all posts. A User’s stars are visible to others, but they are not automatically added to your followers’ streams. + Parameters - + post_id (string, `1`) ... The id of the Post. + + post_id: `1` (string) - The id of the Post. ### Star a Post [POST] Save a given Post to the current User’s stars. This is just a “save” action, not a sharing action.