Merge pull request #135 from apiaryio/zdne/attributes-description

Attributes description

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.
 
+<a name="def-attribute"></a>
+### Attribute
+Based on the context, attribute (property) of a message-body data structure, or attribute of a resource, or an input attribute of a transition – [Action](#def-action).
+
 <a name="def-blueprint"></a>
 ### Blueprint
 An **API description**. A **blueprint file** (or a set of files) that describes an API using the API Blueprint language.
 
+<a name="def-data-structure"></a>
+### Data Structure
+A particular data organization, or a description of it. In API Blueprint, data structures and its [Attributes](#def-attribute) are described using the Markdown Syntax for Object Notation – [MSON][].
+
 <a name="def-entity"></a>
 ### Entity
 [**Entity**](http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html) being transferred in a [payload](#def-payload).
@@ -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
+

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

examples/1. Simplest API.md → 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)

examples/2. Resource and Actions.md → 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).

examples/3. Named Resource and Actions.md → 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. 

examples/4. Grouping Resources.md → 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.

examples/5. Responses.md → 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.

examples/6. Requests.md → 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.

examples/7. Parameters.md → 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)
 

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

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)

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

examples/8. Resource Model.md → 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.