diff --git a/README.md b/README.md index 7e94908..2e1bf27 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,7 @@ Refract is a recursive data structure for expressing complex structures, relatio - [Full Specification](refract-spec.md) - [Data Structure Namespace](namespaces/data-structure-namespace.md) -- [Resource Namespace](namespaces/resource-namespace.md) -- [API Namespace](namespaces/api-namespace.md) +- [API Description Namespace](namespaces/api-description-namespace.md) ## Version diff --git a/namespaces/resource-namespace.md b/namespaces/api-description-namespace.md similarity index 67% rename from namespaces/resource-namespace.md rename to namespaces/api-description-namespace.md index 26dded5..0b0d3a1 100644 --- a/namespaces/resource-namespace.md +++ b/namespaces/api-description-namespace.md @@ -1,11 +1,11 @@ -# Resource Namespace +# API Description Namespace This document extends [Refract][] [Data Structure Namespace][] to define REST Resource data structure elements. ## Content -- [Resource Namespace](#resource-namespace) +- [API Description Namespace](#api-description-namespace) - [Content](#content) - [About this Document](#about-this-document) - [Supporting Data Types](#supporting-data-types) @@ -17,6 +17,8 @@ This document extends [Refract][] [Data Structure Namespace][] to define REST Re - [Resource Elements](#resource-elements) - [Resource (Element)](#resource-element) - [Transition (Element)](#transition-element) + - [Category (Element)](#category-element) + - [Copy (Element)](#copy-element) - [Protocol-specific Elements](#protocol-specific-elements) - [HTTP Transaction (Element)](#http-transaction-element) - [HTTP Headers (Array Type)](#http-headers-array-type) @@ -76,15 +78,15 @@ Arbitrary data asset. - messageBody - Asset is an example of message-body - messageBodySchema - Asset is an schema for message-body - `attributes` (object) - - `contentType` (string) - Optional media type of the asset + - `contentType` (string) - Optional media type of the asset. When this is unset, the content type SHOULD be inherited from the `Content-Type` header of a parent HTTP Message Payload - `href` (Href) - Link to the asset - `content` (string) - A textual representation of the asset -## Resource Elements +## API Description Elements ### Resource (Element) -The Resource representation with its available transitions and attributes. +The Resource representation with its available transitions and its data. #### Properties @@ -162,18 +164,19 @@ Note: At the moment only the HTTP protocol is supported. If not set, the parent `resource` element `href` attribute SHOULD be used to resolve the target URI of the transition. - - `parameters` (Href Variables) - Input parameters. + - `hrefVariables` (Href Variables) - Input parameters. Definition of any input URI path segments or URI query parameters for this transition. - If `href` and `parameters` attributes aren't set, the parent `resource` + If `href` and `hrefVariables` attributes aren't set, the parent `resource` element `hrefVariables` SHOULD be used to resolve the transition input parameters. - - `attributes` (Data Structure) - Input attributes. + - `data` (Data Structure) - Input attributes. 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[HTTP Transaction]) - Array of transaction examples. Transaction examples are protocol-specific examples of REST transaction @@ -195,6 +198,143 @@ Note: At the moment only the HTTP protocol is supported. } ``` +### Category (Element) + +Grouping element – a set of elements forming a logical unit of an API such as +group of related resources or data structures. + +A category element MAY include additional classification of the category. +The classification MAY hint what is the content or semantics of the category. +The classification MAY be extended and MAY contain more than one classes. + +For example a `category` element may be classified both as `resourceGroup` and +`dataStructures` to denote it includes both resource and data structures. It +may also include the `transitions` classification to denote it includes +transitions. + +#### Properties + +- `element`: category (string, fixed) +- `meta` + - `class` (array, fixed) + - (enum[string]) + - api - Category is a API top-level group. + - resourceGroup - Category is a set of resource. + - dataStructures - Category is a set of data structures. + - scenario - Reserved. Category is set of steps. + - transitions - Category is a group of transitions. +- `attributes` + - `meta` (array[Member Element]) - Arbitrary metadata + + Note the "class" of the Member Element can be used to distinguish the + source of metadata as follows: + + - Class `user` - User-specific metadata. Metadata written in the source. + - Class `adapter` - Serialization-specific metadata. Metadata provided by adapter. + +- `content` (array[Element]) + +#### Example + +```json +{ + "element": "category", + "meta": { + "class": [ + "api" + ], + "title": "Polls API" + }, + "attributes": { + "meta": [ + { + "element": "member", + "meta": { + "class": ["user"] + }, + "content": { + "key": { + "element": "string", + "content": "HOST", + }, + "value": { + "element": "string", + "content": "http://polls.apiblueprint.org/" + } + } + } + ] + }, + "content": [ + { + "element": "category", + "meta": { + "class": [ + "resourceGroup" + ], + "title": "Question", + "description": "Resources related to questions in the API." + }, + "content": [] + } + ] +} +``` + +### Copy (Element) + +Copy element represents a copy text. A textual information in API description. +Its content is a string and it MAY include information about the media type +of the copy's content. + +If an element contains a Copy element, the element's `description` metadata +MAY include the Copy element's content. + +The Copy element MAY appear as a content of any element defined in the base +namespaces. + +#### Properties + +- `element`: copy (string, fixed) +- `attributes` (object) + - `contentType`: *text/plain* (string) - Optional media type of the content. +- `content` (string) + +#### Example + +Given an API description with following layout: + +- Group + - Copy "Lorem Ipsum" + - Resource "A" + - Resource "B" + - Copy "Dolor Sit Amet" + +```json +{ + "element": "category", + "meta": { + "description": "Lorem Ipsum\nDolor Sit Amet" + }, + "content": [ + { + "element": "copy", + "content": "Lorem Ipsum" + }, + { + "element": "resource" + }, + { + "element": "resource" + }, + { + "element": "copy", + "content": "Dolor Sit Amet" + } + ] +} +``` + ## Protocol-specific Elements ### HTTP Transaction (Element) @@ -315,8 +455,8 @@ HTTP request message. - `element`: httpRequest (string, fixed) - `attributes` - - `method` (string) - HTTP request method. - - `href` (Href) - A concrete URI for the request. + - `method` (string) - HTTP request method. The method value SHOULD be inherited from a parent transition if it is unset. + - `href` (Href) - A concrete URI for the request. The href SHOULD be inherited from a parent transition by expanding the href and hrefVariables if unset. ### HTTP Response Message (HTTP Message Payload) diff --git a/namespaces/api-namespace.md b/namespaces/api-namespace.md deleted file mode 100644 index 04afc81..0000000 --- a/namespaces/api-namespace.md +++ /dev/null @@ -1,161 +0,0 @@ -# API Namespace - -This document extends [Refract][] [Resource Namespace][] to define REST API data structure elements. - -## Content - - -- [API Namespace](#api-namespace) - - [Content](#content) - - [About this Document](#about-this-document) - - [Category (Element)](#category-element) - - [Copy (Element)](#copy-element) - - -## About this Document - -This document conforms to [RFC 2119][], which says: - -> The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. - -[MSON][] is used throughout this document. - -## Category (Element) - -Grouping element – a set of elements forming a logical unit of an API such as -group of related resources or data structures. - -A category element MAY include additional classification of the category. -The classification MAY hint what is the content or semantics of the category. -The classification MAY be extended and MAY contain more than one classes. - -For example a `category` element may be classified both as `resourceGroup` and -`dataStructures` to denote it includes both resource and data structures. - -### Properties - -- `element`: category (string, fixed) -- `meta` - - `class` (array, fixed) - - (enum[string]) - - api - Category is a API top-level group. - - resourceGroup - Category is a set of resource. - - dataStructures - Category is a set of data structures. - - scenario - Reserved. Category is set of steps. -- `attributes` - - `meta` (array[Member Element]) - Arbitrary metadata - - Note the "class" of the Member Element can be used to distinguish the - source of metadata as follows: - - - Class `user` - User-specific metadata. Metadata written in the source. - - Class `adapter` - Serialization-specific metadata. Metadata provided by adapter. - -- `content` (array[Element]) - -### Example - -```json -{ - "element": "category", - "meta": { - "class": [ - "api" - ], - "title": "Polls API" - }, - "attributes": { - "meta": [ - { - "element": "member", - "meta": { - "class": ["user"] - }, - "content": { - "key": { - "element": "string", - "content": "HOST", - }, - "value": { - "element": "string", - "content": "http://polls.apiblueprint.org/" - } - } - } - ] - }, - "content": [ - { - "element": "category", - "meta": { - "class": [ - "resourceGroup" - ], - "title": "Question", - "description": "Resources related to questions in the API." - }, - "content": [] - } - ] -} -``` - -## Copy (Element) - -Copy element represents a copy text. A textual information in API description. -Its content is a string and it MAY include information about the media type -of the copy's content. - -If an element contains a Copy element, the element's `description` metadata -MAY include the Copy element's content. - -The Copy element MAY appear as a content of any element defined in the base -namespaces. - -### Properties - -- `element`: copy (string, fixed) -- `attributes` (object) - - `contentType`: *text/plain* (string) - Optional media type of the content. -- `content` (string) - -### Example - -Given an API description with following layout: - -- Group - - Copy "Lorem Ipsum" - - Resource "A" - - Resource "B" - - Copy "Dolor Sit Amet" - -```json -{ - "element": "category", - "meta": { - "description": "Lorem Ipsum\nDolor Sit Amet" - }, - "content": [ - { - "element": "copy", - "content": "Lorem Ipsum" - }, - { - "element": "resource" - }, - { - "element": "resource" - }, - { - "element": "copy", - "content": "Dolor Sit Amet" - } - ] -} -``` - ---- - -[MSON]: https://github.com/apiaryio/mson -[Refract]: ../refract-spec.md -[Resource Namespace]: resource-namespace.md