[occi-wg] JSON Rendering

Thu Apr 5 10:46:02 EDT 2012

+1 from me on the separation path. Let's get it proper before it cannot be separated anymore.

-A.

Am 05.04.2012 um 16:43 schrieb "Ralf Nyren" <ralf at nyren.net>:

> 
> On Thu, 5 Apr 2012 09:21:52 +0000, "Feldhaus, Florian"
> <florian.feldhaus at gwdg.de> wrote:
>> Hi,
>> 
>> how do we proceed?
> 
> The best thing IMO would be to create a version 1.2 of the HTTP Rendering
> doc and update it so that it is a clear separation between Protocol and
> Data Format. The existing text/occi, text/occi and the JSON data formats
> would then be pluggable modules to this spec.
> 
> The quick way is to continue writing the JSON rendering as a standalone
> HTTP-based OCCI rendering which happens to be quite similar to the HTTP
> Rendering. Saves time but causes lots of duplication.
> 
>> Following a some responses to your comments:
>> 
>> Am 04.04.2012 um 10:59 schrieb Ralf Nyren:
>> 
>>> On Tue, 03 Apr 2012 14:31:24 +0200, Feldhaus, Florian
>>> <florian.feldhaus at gwdg.de> wrote:
>>> 
>>>> Hi,
>>>> 
>>>> once again I would like to reiterate the JSON rendering. First a short
>>>> overview what Alexander and I think are the main points we should
>>>> address:
>>>> - remove all HTTP Rendering specific parts from the JSON rendering
>>> 
>>> Remember that an OCCI rendering (as currently specified) includes
> _both_
>>> protocol and data format at the moment.
>> 
>> That's only partly true. A "pure" JSON rendering can already exist
>> independently from the HTTP Rendering without any trouble in rendering. 
> 
> No. Yes.
> 
> Probably a misunderstanding here. An OCCI Rendering is defined as a way to
> manipulate the Core Model. So in theory you could have 2 different
> HTTP-based OCCI Renderings with different semantics where one happen to be
> using XML as the data format and the othe JSON for example. This is not
> nice but within the definition.
> 
> So to be complete an OCCI Rendering must both define the protocol and
> whatever data format is used by that protocol.
> 
> This does not prevent us from having a single OCCI HTTP Protocol Rendering
> with pluggable data formats.
> 
>>> I like the idea of having a common HTTP Protocol rendering spec which
>>> the JSON rendering could be built upon though.
>> 
>> I second this and would like to move forward. Any comments on the best
>> strategy? Do we need to create a version 1.2 for the HTTP rendering?
> 
> I believe so yes. It would be mostly backwards compatible though.
> 
>>> However, the current HTTP rendering doc lacks things like e.g. request
>>> parameters in URL which I would say is necessary to have a sane JSON
>>> rendering.
>> 
>> I don't think so. The rendering should be independently of the transport
>> protocol. If I ask your server to send me a file by mail containing the
>> JSON rendering of all resources, that should work as well. 
> 
> We are probably using different terminology here. I am referring to an
> OCCI "rendering". Your statement is 100% true for an OCCI data format.
> However, a data format is not enough to create an OCCI Rendering.
> 
>>>> - consider using RFC 5988 "Web Linking" for collection information
>>>> (e.g. index, next, previous,…)
>>> 
>>> Gary and I had an email conversation which resulted in a solution where
>>> all info necessary for pagination would end up in the request URL. I.e.
>>> basically eliminating the need for using special headers (such as RFC
>>> 5988).
>>> 
>>> The request parameters to a collection simply allow you to specify the
>>> amount of resource instances you want returned either _before_ or
> _after_
>>> a specific occi.core.id.
>> 
>> Do you have some examples? IMHO this should go to the revised HTTP
>> rendering document.
> 
> The mail thread was on occi-wg so should be in the archives.
> 
> Agree that it would be best to put this into a 1.2 version of the HTTP
> Rendering doc.
> 
>>>> Examples:
>>>> http://pastebin.com/ZK9Uf0K1 (Entities)
>>> 
>>> Nice, I like that you keep the "attributes" hash now ;)
>>> 
>>> How do you render Link attributes for the links tied to an OCCI
> Resource?
>> 
>> In the example you can see Links are rendered as a hash containing href
>> and kind. The only really necessary part is the href location.
> Everything
>> else is optional and could be retrieved by the client using separate
> HTTP
>> requests. It would also be possible to omit the hash and just render all
>> link hrefs in an array. To allow for a slim rendering and also allow for
>> additional information to be send to the client, I would suggest that we
>> specify a hash with at least the href and optional all other parameters
>> valid for the link. We could even go so far as to use the link rendering
>> for rendering link attributes within resources.
> 
> After many long discussions it was decided to have inline rendering of
> Link attributes in the OCCI HTTP Rendering. I think the same should apply
> to JSON.
> 
>>>> To keep the mail short, a detailed discussion can be found in the
>>>> attached text document.
>>> 
>>> Just picking out one thread:
>>> 
>>>> resources and links should be represented differently. The entry
>>>> "links" is unique for resources and the entries "target" and "source"
>>>> are unique for links.
>>> 
>>> Sounds goods. So the top-level hash of the collection format would have
>>> one hash "resources" and another hash "links" then?
>>> I mean, we still have to cover the case where the client asks for
>>> "everything" at the top-level URL and thus gets both Resources and
> Links
>>> in the response.
>> 
>> I would suggest to have a content-type for entities. It should contain a
>> hash with "links" and "resources". Both then are arrays of hashes.
> 
> I rather have a single array, it plays much better with the collection
> concept of REST.
> 
>>>> In OCCI Core the attribute names should be changed from
>>>> occi.core.source and occi.core.target to just source and target, as
> both
>>>> are representing connections to other resources from within the OCCI
>>>> model (similar to links in resources, or kind in entity).
>>> 
>>> occi.core.source and occi.core.target was named simply source/target up
>>> until just before the OCCI HTTP Rendering doc was published.
>>> 
>>> The fundamental problem here is that we have two different sorts of
>>> "attributes".
>>> 1. Attributes as part of the OCCI Core model. These include both
>>> Entity.id, Entity.title, Resource.summary, Resource.links, Link.target,
>>> Link.source, etc
>>> 2. Attributes as exposed by an OCCI rendering. The HTTP Rendering
>>> exposes id, title, summary as attributes as well as target and source.
>>> However the Resource.links attribute is not exposed as an attribute...
>>> 
>>> There is no clear distinction here which IMO leads to confusion.
> 
> No comments on the above?
> 
>>> Also remember that a subclass of OCCI Link may have Link.target
> pointing
>>> at some arbitrary external object.
>> 
>> In my opinion, source and target always point to resources, even if they
>> lie outside the OCCI model. They contain complex data types like kind or
>> mixin and not primitive data types like id, title or summary.
> 
> So, to link to a VNC console you would have the vnc:// URL where? In a VNC
> console Resource object?
> 
> /Ralf
> _______________________________________________
> occi-wg mailing list
> occi-wg at ogf.org
> https://www.ogf.org/mailman/listinfo/occi-wg
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 3617 bytes
Desc: not available
URL: <http://www.ogf.org/pipermail/occi-wg/attachments/20120405/8333d9b3/attachment-0001.bin>