Media types

IN PROGRESS

Evaluate Media Types

• start with Collection/JSON
• See later if we want to use HAL in addition or replacement
• note: both "standards" are evolving, so we are likely to update the lib for time to time.

Create/Choose Media Types

• Collection/JSON

Graph Data Model

• content: graphviz’s code
• id: UUID, shortname, integer ..
• title: user friendly title
• description: description of the graph
• (image: generated graph from the graphviz’s code)

Collection-JSON template

{
"collection" :
	{
	"version" : "1.0",
	"href" : URI,
	"links" : [ARRAY],
	"items : [ARRAY],
	"queries" : [ARRAY],
	"template" : {OBJECT},
	"error" : {OBJECT}
	}
}

Collection/JSON Hypermedia API

We will return a full Collection+JSON response including links, queries, the write template, and the list of items.

 {    // based on Collection+JSON media type
      // http://www.amundsen.com/media-types/collection/
     "collection" : {
       "href" : "...",
       "version" : "1.0",
       "links" : [
          {"rel" : "author", "href" : "...", "prompt" : "Author"},
          {"rel" : "profile", "href" : "...", "prompt" : "Profile"}
      ],

    //Queries
      "queries" : [
         {"rel" : "all", "href" : "...", "prompt" : "All Graphs"},
         {"rel" : "byName", "href" : "...", "prompt" : "byName",
         "data" : [
	    {"name" : "name", "value" : "", "prompt" : "Graph Name"},
	  ]
       }
     ],

    //Graph Collections
      "items" : [
	 {"href" : "...",
	  "data" :[
		{"name" : "title", "value" : "...", "prompt" :"Title"},
		{"name" : "content", "value" : "...", "prompt" : "Graphviz Code"},
		{"name" : "id", "value" : "...", "prompt" : "Id"},
		{"name" : "description", "value" : "...", "prompt" : "Description"},
		{"name" : "representation", "value" : "...", "prompt" : "Binary Representation"}
		]
	   }
        ],

    //Graph template
    // Use this date to create a new Graph 
    "template" :
  	     {"data" :[
 	         {"name" : "title", "value" : "...",prompt:"Title"},
	         {"name" : "content", "value" : "...", "prompt" : "Graphviz Code"},
	         {"name" : "description", "value" : "...", "prompt" : "Description"}
	     ]
       }   
   }
   }

Home Page: The collection response

The collection response, we will return a Collection+JSON response including any collection links, queries, the write template, and the list of items. The client sends an HTTP GET request to the root URI and the server return a Collection+JSON Document

REQUEST

    GET / HTTP/1.1
    Host: www.graphviz-server.org
    Accept: application/vnd.Collection+JSON

RESPONSE

   200 OK HTTP/1.1
   Content-Type: application/vnd.Collection+JSON
   Content-Length: xxx
   { "collection" : {...}, ... }

Create a Graph: (Add an item)

To create a new graph (an item) in the collection, the client use the template object to compose a valid graph representation.

  // write template for "Graph" application
  {
    "template" :
     {
       "data" :
        [
	    {"name" : "title", "value" : "a" :"Title"},
	    {"name" : "content", "value" : "", "prompt" : "Graphviz Code"},
	    {"name" : "description", "value" : "", "prompt" : "Description"}
         ]
   }

and then uses HTTP POST to send that representationto the server for processing. If the item resource was created successfully, the server responds with a status code of201 and a Location header that contains the URI of the newly created item resource:

REQUEST

 POST /HTTP/1.1
 Host: www.graphviz-server.org
 Content-Type: application/vnd.Collection+JSON
 { "template" : { "data" : [ ...] } }

RESPONSE

 201 Created HTTP/1.1
 Location: www.graphviz-server.org/GraphUUID_1

The URI returned in the location header, then can be used to read, update, and delete the resource.

Retrieve a Graph (GET an item)

Clients can retrieve an existing Graph (item) resource by sending an HTTP GET request to the URI of an item resource. If the request is valid, the server will respond with a representation of that item resource.

REQUEST

   GET /GraphUUID_1 HTTP/1.1
   Host: www.graphviz-server.org
   Accept: application/vnd.Collection+JSON

RESPONSE

   200 OK HTTP/1.1
   Content-Type: application/vnd.Collection+JSON
   Content-Length: xxx
   { "collection" : { "href" : "...", "items" [ { "href" : "...", "data" : [...].} } }

Note that the valid response is actually a complete collection document that contains only one item (and possibly related queries and template properties).

Updating a Graph (Update an Item)

To update an existing resource, the client uses the template object as a guide to composing a replacement item representation and then uses HTTP PUT to the URI of an item resource to send that representation to the server.If the update is successful, the server will respond with HTTP status code 200 and possibly a representation of the updated item resource representation:

REQUEST

   PUT /GraphUUID_1 HTTP/1.1
   Host: www.graphviz-server.org
   Content-Type: application/vnd.Collection+JSON
   { "template" : { "data" : [ ...] } }

RESPONSE

   200 OK HTTP/1.1

Trash Graph (Delete an item)

Clients can delete existing resources by sending an HTTP DELETE request to the URI of the item resource.If the delete request is successful, the server SHOULD respond with an HTTP statuscode of 204:

REQUEST

    DELETE /GraphUUID_1 HTTP/1.1
    Host: www.graphviz-server.org

RESPONSE

    204 No Content HTTP/1.1

References

1: http://www.amundsen.com/blog/archives/1124 "Mike Amundsen: Rob Conery's API Invitation"

2: http://www.amundsen.com/media-types/collection/ "Collection+JSON"

3: https://github.com/mamund/collection-json "Collection+JSON git repo"

4: https://github.com/jvelilla/CJ "Collection+JSON Eiffel Library"

5: http://shop.oreilly.com/product/0636920020530.do "Building Hypermedia APIs with HTML5 and Node By Mike Amundsen"