zdne/1. what is trait.md Secret

## 1. what is trait.md

      
    Raw
  

              1. what is trait.md
            
          
    What is a Trait

Trait is a quality or characteristic of an API Blueprint object (hereafter just object). At the moment the following sections of API Blueprint are recognized as API Blueprint object:

API
Resource Group
Resource
Resource Model
Action
Request
Response
Parameter

Traits can be used add additional semantics or a set of characteristics to an object.
Semantic Trait

A semantic traits adds a semantic meaning to an object.
Definition of a semantic trait:
# My API
+ Trait A ... Object Quality "A"

Referencing a defined trait:
## Resource 1 [/1]
+ Traits
    + [A][]

In-place definition & use of a semantic trait:
## Resource 1 [/1]
+ Traits
    + A ... Object Quality "A"

NOTE: Traits defined in-place cannot be referenced later
An object can reference multiple traits:
## Resource 1 [/1]
+ Traits
    + [A][]
    + [B][]
    + C ... Object Quality "C"
    + Type = `safe`

Characteristic Trait

In addition to its semantic meaning a trait can also express certain characteristic of object's payload(s).
Where payload characteristic is one of:

parameter characteristic
property characteristic (new in Format 1B)
[request | response] header characteristic
body characteristic
schema characteristic

For example:
# My API
+ Trait Color
    + Response Headers
        + X-Resource-Color (string, `red`) ... Color of the resource.

## Resource 1 [/1]
+ Traits
    + [Color][]

One trait can also represent a set of object characteristics:
# My API
+ Trait Art
    + Headers
        + X-Resource-Color (optional, string, `red`) ... Color of the resource

    + Properties
        + size = `42` (number) ... The size of an object

## Resource 1 [/1]
+ Traits
    + [Art][]


## 2. Formal definition.md

      
    Raw
  

              2. Formal definition.md
            
          
    API Blueprint Trait


1.1 Trait Definition Section

Definition of one API Bluepint object trait. Defining a trait does not inherit the trait.
Any of of the following API Blueprint Sections MAY include one or multiple Trait Definition Sections:

API Section
Resource Group Section
Resource Section
Resource Model Section
Action Section
Request Section
Response Section
Parameter Section

Trait Definition Section is recognized by the Trait reserved keyword written as a Markdown list item. Trait Definition Section has the following syntax:
+ Trait <trait name> [... <description>] 

	[<additional description>]

	[+ Parameters 

		<URI parameters>]

	[+ Properties

		<message-body properties>]

	[+ [Request | Response] Headers

		<message-headers>]

	[+ Body

		<message-body>]

	[+ Schema

		<message-body schema>]

Example:
+ Trait Red

-- or --

+ Trait Green 
	
	This traits means that the object is Green. 

	+ Headers
		+ X-Color = `Green`

A Trait defined in Trait Definition Section can be referenced later in Inherited Traits Section.

1.2 Inherited Traits Section

A list of a traits to be inherited by an API Blueprint Object.
Any of of the sections that may include Trait Definition Sections MAY include one Inherited Traits Section.
Inherited Traits Section is recognized by the Traits reserved keyword written as a Markdown list item. The content of this section is a nested list of references to previously defined traits and/or new Trait Definition Sections.
Example:
+ Traits
    + [Red][]
    + [Green][]
    + Blue

Where Red is a trait previously defined in a Trait Definition Sections and Blue is a in-place definiton of a new trait. An in-place definition is a Trait Definition Section. However a trait defined in-place CANNOT be referenced later.

  
## 3. example: basic auth.md

      
    Raw
  

              3. example: basic auth.md
            
          
    API


Trait Basic Auth

Headers

Authorization (optional, Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==) ... Base 64 encoded credentials


My Resource [/resource]


Request (application/json)


Traits

[Basic Auth][]


Headers
  X-My-Header: 1


Response 200
  Hello World


## 4. example: oauth2.md

      
    Raw
  

              4. example: oauth2.md
            
          
    API


Trait OAuth2
OAuth token can be sent either as a URI query parameter or as an HTTP request header.


Parameters

access_token (optional, string) ... OAuth2 Token (sent in a header)


Headers

Authorization (optional, Authorization: token OAUTH-TOKEN) ... OAuth2 Token (sent as a parameter)


My Resource [/resource]


Request

Traits

[OAuth2][]


Response 200
  Hello World!


## 5. example: gist fox api.md

      
    Raw
  

              5. example: gist fox api.md
            
          
    FORMAT: 1B
Gist Fox API

Gist Fox API is a pastes service similar to GitHub's Gist.
Authentication

Gist Fox API uses OAuth Authorization. First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token' scope.


Trait Basic Auth

Request Headers

Authorization (Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==) ... Base 64 encoded login credentials.


Trait OAuth2


Parameters

access_token (optional, string) ... OAuth2 Token (sent in a header)


Request Headers

Authorization (optional, Authorization: token OAUTH-TOKEN) ... OAuth2 Token (sent as a parameter)


Media Types

Where applicable this API uses the HAL+JSON media-type to represent resources states and affordances.
Requests with a message-body are using plain JSON to set or update resource states.
Error States

The common HTTP Response Status Codes are used.
Gist Fox API Root [/]

Gist Fox API entry point.
This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and
HAL links.
Retrieve the Entry Point [GET]


Response 200 (application/hal+json)


Headers
  Link: <http:/api.gistfox.com/>;rel="self",<http:/api.gistfox.com/gists>;rel="gists",<http:/api.gistfox.com/authorization>;rel="authorization"


Body
  {
      "_links": {
          "self": { "href": "/" },
          "gists": { "href": "/gists?{since}", "templated": true }
          "authorization": { "href": "/authorization"}
      }
  }


Group Gist

Gist-related resources of Gist Fox API.
Gist [/gists/{id}]

A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note.
The Gist resource has the following attributes:

id
created_at
description
content

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.


Model (application/hal+json)
HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links.


Headers
  Link: <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"


Body
  {
      "_links": {
          "self": { "href": "/gists/42" },
          "star": { "href": "/gists/42/star" },
      },
      "id": "42",
      "created_at": "2014-04-14T02:15:15Z",
      "description": "Description of Gist",
      "content": "String contents"
  }


Retrieve a Single Gist [GET]


Response 200
[Gist][]


Edit a Gist [PATCH]

To update a Gist send a JSON with updated value for one or more of the Gist resource attributes. All attributes values (states) from the previous version of this Gist are carried over by default if not included in the hash.


Request (application/json)
  {
      "content": "Updated file contents"
  }


Response 200
[Gist][]


Delete a Gist [DELETE]


Traits

[OAuth2][]


Response 204


Gists Collection [/gists{since}]

Collection of all Gists.
The Gist Collection resource has the following attribute:

total

In addition it embeds Gist Resources in the Gist Fox API.


Model (application/hal+json)
HAL+JSON representation of Gist Collection Resource. The Gist resources in collections are embedded. Note the embedded Gists resource are incomplete representations of the Gist in question. Use the respective Gist link to retrieve its full representation.


Headers
  Link: <http:/api.gistfox.com/gists>;rel="self"


Body
  {
      "_links": {
          "self": { "href": "/gists" }
      },
      "_embedded": {
          "gists": [
              {
                  "_links" : {
                      "self": { "href": "/gists/42" }
                  },
                  "id": "42",
                  "created_at": "2014-04-14T02:15:15Z",
                  "description": "Description of Gist"
              }
          ]
      },
      "total": 1
  }


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.


Response 200
[Gists Collection][]


Create a Gist [POST]

To create a new Gist simply provide a JSON hash of the description and content attributes for the new Gist.


Traits

[OAuth][]


Parameters

access_token (string, optional) ... Gist Fox API access token.


Request (application/json)
  {
      "description": "Description of Gist",
      "content": "String content"
  }


Response 201
[Gist][]


Star [/gists/{id}/star{?access_token}]

Star resource represents a Gist starred status.
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.


Model (application/hal+json)
HAL+JSON representation of Star Resource.


Headers
  Link: <http:/api.gistfox.com/gists/42/star>;rel="self"


Body
  {
      "_links": {
          "self": { "href": "/gists/42/star" },
      },
      "starred": true
  }


Star a Gist [PUT]

This action requries an access_token with gist_write scope.

Response 204

Unstar a Gist [DELETE]

This action requries an access_token with gist_write scope.

Response 204

Check if a Gist is Starred [GET]


Response 200
[Star][]


Group Access Authorization and Control

Access and Control of Gist Fox API OAuth token.
Authorization [/authorization]

Authorization Resource represents an authorization granted to the user. You can only access your own authorization, and only through Basic Authentication.
The Authorization Resource has the following attribute:

token
scopes

Where token represents an OAuth token and scopes is an array of scopes granted for the given authorization. At this moment the only available scope is gist_write.


Traits

[Basic Auth][]


Model (application/hal+json)


Headers
  Link: <http:/api.gistfox.com/authorizations/1>;rel="self"


Body
  {
      "_links": {
          "self": { "href": "/authorizations" },
      },
      "scopes": [
          "gist_write"
      ],
      "token": "abc123"
  }


Retrieve Authorization [GET]


Response 200
[Authorization][]


Create Authorization [POST]


Request (application/json)
  {
      "scopes": [
          "gist_write"
      ]
  }


Response 201
[Authorization][]


Remove an Authorization [DELETE]


Response 204


## 6. format changes.md

      
    Raw
  

              6. format changes.md
            
          
    Related Format Changes in 1B


Payload Properties
Nested Parameters
Parametric Headers

New Payload Structure in 1B

+ Payload (<media type>)
	
	[<description>]

	+ Traits
		<traits>

	+ Parameters
		<uri parameters>

	+ Properties
		<entity-body properties>

	+ Headers
		<entity-headers>

	+ Body
		<entity-body> 

	+ Schema
		<entity-schema>


## 7. parameters and attributes.md

      
    Raw
  

              7. parameters and attributes.md
            
          
    Use of Parameters & Attributes in API Blueprint

Parameters of an HTTP Request


HTTP Request Method
URI Parameters
Query Parameters
Entity-header Parameters (metadata)
Entity-body Parameters

Attributes of an HTTP Response


Entity-header Attributes
Entity-body Attributes

Resource Attributes (Properties, Semantic Descriptors)


Metadata (meta attributes)
Data (attributes)

Resource Affordances (Actions, State Transitions)


Relation
Link


Naming Proposal

Use the term "properties" for request entity-body rarameters & response entity-body attributes e.g. "entity-body properties".

  
## 8. linking.md

      
    Raw
  

              8. linking.md
            
          
    Links

Trait


Headers
  X: 42


Trait
[F]: #Something "X"
Is here


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum auctor, lectus ac luctus cursus, dui felis condimentum turpis, sagittis posuere nunc diam vel mauris. Donec lectus urna, vulputate eu eros vitae, egestas gravida arcu. Nunc vitae lacus quis lacus elementum sollicitudin at quis ipsum. Fusce aliquam ante sit amet felis aliquam porta. Sed dui dui, commodo sed iaculis et, rutrum eu sem. Aliquam suscipit lacus sem, sed elementum urna blandit a. Proin risus lorem, viverra nec risus vel, lacinia posuere libero. Curabitur sed tortor a arcu vulputate ornare. Duis volutpat tortor quam, quis bibendum sem gravida non. Etiam dolor odio, dictum non vehicula quis, mollis vel mauris. Nunc lacinia porttitor luctus. Vivamus sit amet metus vel metus condimentum tempus.
Nullam mattis mi quis quam interdum vulputate. In urna odio, venenatis ac malesuada eu, iaculis vel purus. Mauris vulputate nisl eu quam luctus varius. Pellentesque nisi ligula, pulvinar eget rutrum et, fermentum sed arcu. Vestibulum congue a turpis feugiat tincidunt. Vivamus nec magna ac sapien ultricies faucibus id sit amet mi. Phasellus interdum, enim vitae bibendum vestibulum, purus ante volutpat tortor, in aliquam elit justo id diam. Mauris condimentum sapien orci, nec lobortis mi sodales in. Quisque tempor turpis sed libero eleifend, ac imperdiet diam semper. Nullam vehicula nisl ac purus mattis placerat. Nullam arcu elit, vestibulum nec eros non, venenatis eleifend metus. Nam varius augue a nibh accumsan, at fermentum elit vestibulum. Nunc est ipsum, fermentum non sapien nec, vulputate aliquam arcu. Curabitur nibh nulla, commodo id justo sit amet, malesuada semper urna. Ut viverra varius tellus mattis tincidunt.
Phasellus non magna nec neque porta viverra. In euismod tristique enim in molestie. In in est metus. Nulla et orci sapien. Nullam ultricies pharetra suscipit. Donec luctus vitae est vel viverra. Suspendisse sodales augue vitae vestibulum consequat. Fusce at urna laoreet, hendrerit diam ac, malesuada quam. Nam semper lacus sit amet leo consequat eleifend. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos.
Nunc volutpat, quam ac tristique semper, nisi odio feugiat urna, eget commodo diam nibh sed tellus. Phasellus condimentum turpis nec metus commodo dignissim. Aliquam fermentum, mauris et placerat tincidunt, diam magna sollicitudin purus, non bibendum magna lorem non nisi. Morbi molestie nec massa bibendum interdum. Fusce porttitor venenatis neque pharetra faucibus. Integer scelerisque lorem vitae orci viverra dictum. Praesent mattis venenatis justo hendrerit rutrum. Quisque ac felis nec est elementum condimentum eu et nisi. Vivamus mattis velit leo, at tristique justo viverra quis.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum auctor, lectus ac luctus cursus, dui felis condimentum turpis, sagittis posuere nunc diam vel mauris. Donec lectus urna, vulputate eu eros vitae, egestas gravida arcu. Nunc vitae lacus quis lacus elementum sollicitudin at quis ipsum. Fusce aliquam ante sit amet felis aliquam porta. Sed dui dui, commodo sed iaculis et, rutrum eu sem. Aliquam suscipit lacus sem, sed elementum urna blandit a. Proin risus lorem, viverra nec risus vel, lacinia posuere libero. Curabitur sed tortor a arcu vulputate ornare. Duis volutpat tortor quam, quis bibendum sem gravida non. Etiam dolor odio, dictum non vehicula quis, mollis vel mauris. Nunc lacinia porttitor luctus. Vivamus sit amet metus vel metus condimentum tempus.
Nullam mattis mi quis quam interdum vulputate. In urna odio, venenatis ac malesuada eu, iaculis vel purus. Mauris vulputate nisl eu quam luctus varius. Pellentesque nisi ligula, pulvinar eget rutrum et, fermentum sed arcu. Vestibulum congue a turpis feugiat tincidunt. Vivamus nec magna ac sapien ultricies faucibus id sit amet mi. Phasellus interdum, enim vitae bibendum vestibulum, purus ante volutpat tortor, in aliquam elit justo id diam. Mauris condimentum sapien orci, nec lobortis mi sodales in. Quisque tempor turpis sed libero eleifend, ac imperdiet diam semper. Nullam vehicula nisl ac purus mattis placerat. Nullam arcu elit, vestibulum nec eros non, venenatis eleifend metus. Nam varius augue a nibh accumsan, at fermentum elit vestibulum. Nunc est ipsum, fermentum non sapien nec, vulputate aliquam arcu. Curabitur nibh nulla, commodo id justo sit amet, malesuada semper urna. Ut viverra varius tellus mattis tincidunt.
Phasellus non magna nec neque porta viverra. In euismod tristique enim in molestie. In in est metus. Nulla et orci sapien. Nullam ultricies pharetra suscipit. Donec luctus vitae est vel viverra. Suspendisse sodales augue vitae vestibulum consequat. Fusce at urna laoreet, hendrerit diam ac, malesuada quam. Nam semper lacus sit amet leo consequat eleifend. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos.
Nunc volutpat, quam ac tristique semper, nisi odio feugiat urna, eget commodo diam nibh sed tellus. Phasellus condimentum turpis nec metus commodo dignissim. Aliquam fermentum, mauris et placerat tincidunt, diam magna sollicitudin purus, non bibendum magna lorem non nisi. Morbi molestie nec massa bibendum interdum. Fusce porttitor venenatis neque pharetra faucibus. Integer scelerisque lorem vitae orci viverra dictum. Praesent mattis venenatis justo hendrerit rutrum. Quisque ac felis nec est elementum condimentum eu et nisi. Vivamus mattis velit leo, at tristique justo viverra quis.
A
B
¹[]
D
E
[F][]
Footnotes


#C ↩


## 9. scratchpad.md

      
    Raw
  

              9. scratchpad.md
            
          
    Scratchpad – thoughts in progress

Concerns


Distinguish between definition of a trait and its actual use. Be able to define a trait without actually using it at that point.
Default trait characteristic to a payload characteristic?

Setting trait characteristic's value:

+ Trait ALPS Profile
    + type ... Type of [ALPS profile](http://amundsen.com/hypermedia/profiles/)
        + Values
            + `semantic`
            + `safe`
            + `unsafe`

# Resource 1 [/1]
+ Traits
    + [ALPS Profile][]
        + type = `semantic`