[occi-wg] Preliminary JSON rendering draft, discussion material

Tue Jan 3 08:29:26 EST 2012

Hi,

happy new year to all of you!

During the last months, I made several notes regarding OCCI and I'd like
to share them with the group. As JSON is currently the most pressing
matter for a lot of implementations, let me start with the JSON rendering.

The draft JSON rendering of Ralf can be found under [1].

# 3 Mandatory HTTP headers

As far as I understand it, the only HTTP headers specific for JSON are
Content-Type and Accept. Both should be set to application/json if JSON is
requested / supplied as per RFC 4627 [2]. Ralf put application/occi+json
into the document. If we indeed want to create our own MIME-Types, we may
have a look at the way CDMI is handling this - see [3]. I would prefer
application/json or specific new MIME types like application/occi-entity
or application/occi-object, application/occi-category ,
application/occi-capability (for /-/ listing).

We had a discussion of mandatory HTTP headers for non text/occi renderings
a few months ago on the IRC chat. As far as I can remember we thought
about the following to be included in all headers
- request HTTP header	
 * Category - thus the client/server can identify the entity type before
the body arrives. Also category is expected to be reasonable small - all
other OCCI information should be rendered in the body due to size
restrictions of the HTTP header. The size restriction can occur due to
restrictions of the webserver, but also due to proxies which change the
HTTP header. To be on the safe side, the header size should be no more
than 4KB.
- response HTTP header
 * Location - When a resource is created and the response code 201 is
returned, the Location header must be set as per RFC2616
- all other OCCI information should only be rendered in the body, see
explanation above.

What are your comments? We might want to put the recommendations we agree
upon into the OCCI HTTP Rendering document.

# 4 JSON representation

In Ralfs approach, the rendering of the resource listing contains all
information on all resources. I don't think this is a good idea. The
resource listing commands (e.g. GET / or GET /compute/) should continue to
return only the URLs for the resources. Maybe we could also recommend,
that text/uri-list should be used for this. The reason, why I don't think
it's a good idea to return all information is, that the JSON structure
gets really large and as you can currently see at Ralfs implementation,
the response time of the server is reduced. Also parsing of the JSON
structure takes a lot longer. The advantage is, that only one HTTP request
is required and all objects are in one large data structure and can be
sorted easily by the client. In the end, speed is more important than
convenience on the client side IMHO. Also this would mix up concepts which
may leads to confusion.

The pagination of GET requests may also prove to be problematic, as
resources may be deleted between successive GET requests. As mentioned
above, I would prefer to have the OCCI server return ALL OCCI-Locations
for a GET request and then let the client do additional GET requests for
each resource.

Besides that, I like the JSON rendering proposed by Ralf. I would like to
suggest, that we extend the Attribute rendering with two additional fields
namely "Range" or "Allowed Values" and "Default". The "Default" Value
would help a lot in defining templates and the "allowed values" will help
the client to present e.g. a slider with min/max for amount of memory or
number of cores.

What are your thoughts? How should we proceed with writing the document?

Cheers,
Florian

-- 

[1] OCCI JSON Rendering Draft:
http://www.ogf.org/pipermail/occi-wg/2011-September/002684.html
[2] RFC 4627: http://www.ietf.org/rfc/rfc4627.txt
[3] RFC 6208: http://www.ietf.org/rfc/rfc6208.txt

Am 18.09.11 22:01 schrieb "Ralf Nyren" unter <ralf at nyren.net>:

>Hi all,
>
>I won't be able to attend OGF in Lyon, too bad but that's how it is.
>Since  
>I wouldn't want you to think I am sneaking away from all the hard work I
>put together a pre-pre-draft of a possible JSON rendering.
>
>I have commit'ed a json_rendering.tex file to the occi-wg repository and
>have attached the generated PDF.
>
>Please look at this document as a basis for further discussions. It is
>very far from being complete and lots of things could certainly be more
>elegant.
>
>Highlights are:
>  - Filtering through query parameters. I.e. no need to use the
>X-OCCI-Attribute to transfer filtering info in GET requests.
>  - Pagination of collections.
>  - Attribute type information (e.g. float, integer, string, etc) relayed
> 
>through the Category definition.
>
>I will try and join in remotely tomorrow.
>
>Best regards, Ralf_______________________________________________
>occi-wg mailing list
>occi-wg at ogf.org
>http://www.ogf.org/mailman/listinfo/occi-wg