JSON HAL API example

HAL Media Type Design for Graphviz server.

IN PROGRESS

Create/Choose Media Types

• HAL+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)

Home Page: The collection response

REQUEST

    GET / HTTP/1.1
    Host: www.graphviz-server.org
    Accept: application/hal+json

RESPONSE

   200 OK HTTP/1.1
   Content-Type: application/hal+json
   Content-Length: xxx
   {}

Create a Graph: (Add an item)

To create a new graph (an item), the client will send A POST request to / and will create a graph resource The Location header links to the graph resource that was created. It is optional to add the JSON-HAL representation of that resource as the POST response, but not required. If the item resource was created successfully, the server responds with a status code of 201 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/json
 Accept: application/hal+json

  { 
      content :”digraph Web{ CLIENT -> SERVER   SERVER -> CLIENT }”
  }

RESPONSE

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

The URI returned in the location header, 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/hal+json

RESPONSE

   200 OK HTTP/1.1
   Content-Type: application/hal+json
   Content-Length: xxx
   { }

Updating a Graph (Update an Item)

REQUEST

   PUT /GraphUUID_1 HTTP/1.1
   Host: www.graphviz-server.org
   Content-Type: application/json
   Accept: application/hal+json 
   {  }

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://tools.ietf.org/html/draft-kelly-json-hal-03 "Mike Kelly: JSON HAL specification"

2: http://stateless.co/hal_specification.html "JSON HAL"

3: http://groups.google.com/group/hal-discuss "HAL mailing list"

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

5: https://github.com/mikekelly/hal_specification "HAL github repo"

6: http://blog.stateless.co/ "Mike Kelly Blog"

7: http://haltalk.herokuapp.com/ "HAL Browser"