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 :

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 :

...

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@ogf.org http://www.ogf.org/mailman/listinfo/occi-wg

I completely agree with Ralf on the need for pagination. It's also worth looking at OpenStack's approach to pagination [1] as we have the semantics and syntax in the OCCI model to support this. Andy [1] http://docs.openstack.org/api/openstack-compute/1.1/content/Paginated_Collec... -----Original Message----- From: occi-wg-bounces@ogf.org [mailto:occi-wg-bounces@ogf.org] On Behalf Of Ralf Nyren Sent: Thursday, January 19, 2012 11:16 AM To: florian.feldhaus@tu-dortmund.de Cc: occi-wg@ogf.org Subject: Re: [occi-wg] Preliminary JSON rendering draft, discussion material Nice summary Florian! Just one comment on the pagination issue, see below. On Thu, 19 Jan 2012 10:53:04 +0000, wrote:

...

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.

I still believe we need pagination, client needs a way to avoid getting drowned in large collection responses. Pagination is not a problem if the server does not guarantee that "page 2" is based on the exact same collection as "page 1". We simply say that in requesting collection items 10-20 you get those item based on the collection at the time of the request. Example: - Client request items 1-10 - A new item is added as "number 2" in the collection (based on the sorting rules chosen by the server implementation) - Client requests items 11-20. The client will see item "10" again but as number 11 in the list this time. This should be easy enough to implement on the server side and this kind of pagination is better than none at all. What do you think? /Ralf _______________________________________________ occi-wg mailing list occi-wg@ogf.org https://www.ogf.org/mailman/listinfo/occi-wg ------------------------------------------------------------- Intel Ireland Limited (Branch) Collinstown Industrial Park, Leixlip, County Kildare, Ireland Registered Number: E902934 This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies.

The OpenStack approach looks interesting. If understand it correctly,

On Thu, 19 Jan 2012 12:58:55 +0000, wrote: then

they use the "marker" to specify the ID of an element. The IDs are whole numbers and not UUIDs like in OCCI. Thus it may be a problem to directly map it to OCCI as UUIDs are not incremental. I would suggest, that we use the approach suggested by Ralf, but maybe expect the server to sort the entities by create time in descending order, as is specified for OpenStack.

Will have a look at the OpenStack approach.

How do we proceed with the document? Is it available somewhere? Can I edit it? How do we coordinate finnishing the JSON rendering? Is the json_rendering.tex in the OCCI SVN (see [1]) the latest version? Should I / we update that document?

The latest version should be in OCCI SVN. We can update it together if you like but please follow the "Directives for using LaTeX with version control systems" [1]. Most importantly do not introduce unnecessary line breaks such as re-indenting paragraphs (*poke* Thijs ;). That and commit'ing chunks of smaller increments will make merging so much easier. Also need to find a suitable way to formally specify the JSON structures. Using ABNF which includes JSON syntax may become be unnecessarily complex. regards, Ralf [1] http://en.wikibooks.org/wiki/LaTeX/Collaborative_Writing_of_LaTeX_Documents

Cheers, Florian

[1]

https://forge.ogf.org/integration/viewcvs/viewcvs.cgi/trunk/json_rendering.

tex?root=occi-wg&rev=491&system=exsy1001&view=log

Am 19.01.12 12:46 schrieb "Edmonds, AndrewX" unter :

...

I completely agree with Ralf on the need for pagination. It's also worth looking at OpenStack's approach to pagination [1] as we have the semantics and syntax in the OCCI model to support this.

Andy

[1] http://docs.openstack.org/api/openstack-compute/1.1/content/Paginated_Coll ections-d1e664.html

-----Original Message----- From: occi-wg-bounces@ogf.org [mailto:occi-wg-bounces@ogf.org] On Behalf Of Ralf Nyren Sent: Thursday, January 19, 2012 11:16 AM To: florian.feldhaus@tu-dortmund.de Cc: occi-wg@ogf.org Subject: Re: [occi-wg] Preliminary JSON rendering draft, discussion material

Nice summary Florian! Just one comment on the pagination issue, see below.

On Thu, 19 Jan 2012 10:53:04 +0000, wrote:

...

...

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.

I still believe we need pagination, client needs a way to avoid getting drowned in large collection responses.

Pagination is not a problem if the server does not guarantee that "page 2" is based on the exact same collection as "page 1".

We simply say that in requesting collection items 10-20 you get those item based on the collection at the time of the request.

Example: - Client request items 1-10 - A new item is added as "number 2" in the collection (based on the sorting rules chosen by the server implementation) - Client requests items 11-20. The client will see item "10" again but as number 11 in the list this time.

This should be easy enough to implement on the server side and this kind of pagination is better than none at all.

What do you think?

/Ralf _______________________________________________ occi-wg mailing list occi-wg@ogf.org https://www.ogf.org/mailman/listinfo/occi-wg ------------------------------------------------------------- Intel Ireland Limited (Branch) Collinstown Industrial Park, Leixlip, County Kildare, Ireland Registered Number: E902934

This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies.