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

Thu Jan 19 05:53:04 EST 2012

Hi,

I'd like to sum up the discussion we had in last weeks TelCo on the JSON
rendering:

Am 03.01.12 14:29 schrieb "Feldhaus, Florian" unter
<florian.feldhaus at tu-dortmund.de>:

>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 came to the conclusion, that using specific MIME types for different
OCCI types would be a good idea, but if we have more than one rendering,
then we need MIME types for each OCCI type and rendering (e.g.
application/occi-capability-json). This may not be feasible. Thus we
agreed, that application/occi+json might be the best option, as the OCCI
type is specified in the OCCI Category field as well.

>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.

Gary pointed out, that all non-standard HTTP headers might be a problem
due to increased Cross-Site scripting problems, many modern browsers
reject custom HTTP headers. Thus I would recommend, that we remove all
non-standard HTTP headers from all renderings except text/occi (which,
IMHO should only be used for testing and then only for requests due to the
header size restrictions).

>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.

Ralf convinced me, that having all entities rendered in one GET is not a
bad idea. It'll help showing all relevant information in a portal and
makes using OCCI easier. The problem of large numbers of entities can and
should be reflected in the documents. Clients should use text/uri-list if
they only need a list of entities and should consider the existing
filtering mechanisms to reduce the number of entities returned by the
server.

>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.

We couldn't touch this subject properly in the call. From my point of
view, paginating requests is not a good idea, as we break the non-stateful
REST concept. We might consider the HTTP header field range to achieve
this behaviour. In general, I would prefer not to have pagination due to
the problem that it may be possible to add or remove entities from the
list between two consecutive requests with pagination.

>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.

Ralf also backs the idea of having a range, allowed values and a default
for the attribute definition within categories.

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

It would be great if we could finnish a first complete draft of the JSON
rendering as soon as possible. Then we'll be able to add this into our
implementations before the plugfest and test it there.

>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
>