Add support for defining hypermedia affordances

Resolves apiaryio#18

Author: smizell

docs/element-definitions.md

@@ -189,6 +189,10 @@ Note: At the moment only the HTTP protocol is supported.
         The value of `relation` attribute SHOULD be interpreted as a link relation
         between transition's parent resource and the transition's target resource
         as specified in the `href` attribute.
+        
+        If a custom relation is being used, it SHOULD be defined using an
+        Affordance Element, and the value of the `relation` property SHOULD be
+        the `id` of the defined affordance.
 
     - `href` (Templated Href) - The URI template for this transition.
 
@@ -211,6 +215,7 @@ Note: At the moment only the HTTP protocol is supported.
         Definition of any input message-body attribute for this transition.
 
     - `contentTypes` (array[String]) - A collection of content types that MAY be used for the transition.
+
 - `content` (array)
     - (Copy) - Transition description's copy text.
     - (HTTP Transaction) - An instance of transaction example.
@@ -234,6 +239,49 @@ Note: At the moment only the HTTP protocol is supported.
 }
 ```
 
+### Affordance (Base API Element)
+
+An affordance element provides a way to provide affordance definitions for the
+API. These definitions can describe link relations used in a Transition Element,
+along with defining unsafe and idempotent transitions.
+
+While data structures are used for defining semantics around data models,
+affrodances are used for defining semantics around hypermedia state transitions.
+
+The control types used here are based on the types used in [ALPS][]. The meta
+property `id` SHOULD be used to define the machine-usable name of the
+affordance.
+
+#### Properties
+
+- `element`: affordance
+- `attributes`
+    - `controlType` (enum)
+        - safe - A hypermedia control that triggers a safe, idempotent state
+          transition (e.g. HTTP.GET or HTTP.HEAD).
+        - unsafe - A hypermedia control that triggers an unsafe, non-idempotent
+          state transition (e.g. HTTP.POST).
+        - idempotent - A hypermedia control that triggers an unsafe, idempotent
+          state transition (e.g. HTTP.PUT or HTTP.DELETE).
+- `content` (array)
+    - (Copy)
+    
+#### Example
+
+```json
+{
+    "element": "affordance",
+    "meta": {
+        "id": "self",
+        "title": "Self"
+    },
+    "attributes": {
+        "controlType": "safe"
+    },
+    "content": []
+}
+```
+
 ### Category (Base API Element)
 
 Grouping element – a set of elements forming a logical unit of an API such as
@@ -260,6 +308,7 @@ transitions.
             - scenario - Category is set of steps.
             - transitions - Category is a group of transitions.
             - authSchemes - Category is a group of authentication and authorization scheme definitions
+            - affordances - Category is a group of affordances
 - `attributes`
     - `meta` (array[Member Element]) - Arbitrary metadata
 
@@ -531,6 +580,11 @@ HTTP response message.
 - `element`: httpResponse (string, fixed)
 - `attributes`
     - `statusCode` (number) - HTTP response status code.
+- `content` (array)
+    - (Affordance) - Expected affordance for the given payload
+    
+        The Ref Element MAY be used to reference existing affordances defined
+        elsewhere.
 
 ## Data Structure Elements
 
@@ -1756,6 +1810,7 @@ These elements and definitions are referenced as part of the base Refract specif
 [MSON]: https://github.com/apiaryio/mson
 [MSON Reference]: https://github.com/apiaryio/mson/blob/master/MSON%20Reference.md
 [Refract]: https://github.com/refractproject/refract-spec/blob/master/refract-spec.md
+[ALPS]: https://tools.ietf.org/html/draft-amundsen-richardson-foster-alps-01#section-2.2.12
 
 [API Description Elements]: definitions/api-description-elements.md
 [Data Structure Elements]: definitions/data-structure-elements.md

docs/overview.md

@@ -1,6 +1,6 @@
 # API Elements Overview
 
-**Version**: 1.0.0-rc1
+**Version**: 1.1.0
 
 **Mime Type**: TBD
 
@@ -37,6 +37,7 @@ It is also helpful to know the relationship between elements. The list below sho
     - Data Structure
     - Category (Group of Resource Elements)
     - Category (Group of Authentication and Authorization Scheme Definitions)
+    - Category (Group of Affordance Elements)
     - Resource
         - Copy
         - Data Structure
@@ -52,6 +53,7 @@ It is also helpful to know the relationship between elements. The list below sho
                 - HTTP Response
                     - Copy
                     - Data Structure
+                    - Affordance
                     - Asset
 
 This main API Category element MAY also be wrapped in a Parse Result element for conveying parsing information, such as source maps, warnings, and errors.
@@ -104,6 +106,10 @@ const transaction = query(apielements, {element: 'httpTransaction'})[0];
 
 Given that API Elements use [Refract][], the structure of the document is recursive by nature. When looking for specific elements, it is best then to walk the tree to look for a match. Querying the tree means that your code will be decoupled not only from specific API description documents, but it will also be decoupled from the structure of those documents.
 
+## Managing Compatibility
+
+When parsing an API Elements document, parsers should safely ignore any elements that were not in the API Elements specification at the time of implementation. This allows for the specification to evolve using semantic versioning and introduce non-breaking changes. 
+
 [Refract]: https://github.com/refractproject/refract-spec/blob/master/refract-spec.md
 [MSON]: https://github.com/apiaryio/mson
 [RFC 2119]: https://datatracker.ietf.org/doc/rfc2119/