[occi-wg] JSON Rendering proposal, rev 2

[Gary Mazz]

On 2/29/2012 4:11 AM, Ralf Nyren wrote:
> On Wed, 29 Feb 2012 09:36:50 +0100, 
> <alexander.papaspyrou at tu-dortmund.de> wrote:
>
>>> I have tried to incorporate much of the feedback received so far. 
>>> Short summary:
>>> - Use separate media-types for rendering the different payload 
>>> contents. Inspired from Florians references to the CDMI spec.
>>
>> I'm not sure whether I really like the different media types, and I 
>> think it could be done without. This would make the content type 
>> negotiation easier, if you consider clients that handle different 
>> renderings at the same time in conjunction with servers that deliver 
>> several different renderings.
>
> Sure, the media-type negotiation will involve a few more bytes in the 
> Accept header but I don't see that as such a big deal. But lets leave 
> that issue for the moment and just look at the payload _received_ by a 
> server or client.
>
> The HTTP protocol's use of Accept and Content-Type headers basically 
> work like this:
> Client: Give me the content of this URL, I can handle (Accept) this 
> list of different formats (media-types) and I really prefer you to use 
> format X or Y if you can, please.
> Server: Look at content pointed to by URL and try to return something 
> that satisfies the client.
> Client: Look at the Content-Type and apply decoding/processing based 
> on media-type alone.
>
> So, essentially the Client do not know what the Server will return. 
> The media-type should be enough to tell the Client what to do with the 
> payload. I rather have it that the Client does not have to poke around 
> within the payload to figure out what to do with it (e.g. the html 
> rendering mess).

The fact that the client doesn't know what the server will return is 
incidental. If the client couldn't discriminate and handle the formats, 
it shouldn't be requesting them in the accept header.  The challenge 
here is whether there is sufficient information returned in the payload 
for the client to distinguish the content, which I'm not too sure is 
relevant. Since JSON is a data format and the returned content is 
associated with an occi applications's taxonomy and ontology, their 
needs to way, explicitly defined or implicate to client/server 
relationship, for the client to understand the returned information.

It can be argued that the nature of http over tcp is sequential and lock 
stepped by definition. So, the client should be 'expecting' a known 
taxonomy based on the request(s) issued. I didn't notice any 
capabilities supporting for multiple queued requests on a connection and 
any capabilities supporting out of order request completion on the same 
connection.

Based on the traditional nature of the http client/server protocol, 
saying the media type is json should be sufficient. If at some time in 
the future, request queuing on a connection is supported, depending on 
method implemented it should be revisited.

>
>> If we go for HTTP-based usage of the JSON rendering, it should just 
>> be application/json.
>
> No, I disagree. By saying application/json the receiver only knows 
> about the syntax. Let's say you get a bunch of data with media-type 
> application/json. Ok, you can decode the json data but then what? You 
> have no clue about the semantics of the format. I believe there is a 
> reason that the Atom Syndication Format use media type 
> application/atom+xml and not just application/xml.
>
> If you happen to be a browser you just throw the json structures at 
> the user and let him figure out what it means. For OCCI however your 
> typical client may be a machine and then it needs to know how to 
> interpret the json structures.
>
> So at a minimum we should say application/occi+json. But in that case 
> we need something in the json structures to say e.g. "format": 
> "entity" vs "format": "discover" in order to distinguish between the 
> different data representation formats. And no, I don't want the 
> one-format-fits-all we did for the HTTP rendering. Therefore I vote on 
> having separate media-types for each data representation format.
>
>> This brings me to the second issue I have: I don't think that it is a 
>> good idea to mix JSON data rendering, and the introduction of a 
>> JSON-based protocol. I am perfectly fine with the former, but for the 
>> latter, we really have HTTP. This might require certain modifications 
>> to the HTTP core API (although I wouldn't bet for it without 
>> checking), but it would keep things nicely separate.
>
> This is a very good point, I agree we should avoid creating a JSON 
> protocol.
>
> However, we do not have a clean OCCI HTTP Protocol spec today. The 
> HTTP Rendering doc is a happy mix of both protocol and data format 
> stuff. Since much of the multi-resource support was added in a hurry 
> just before public comment there are things in there that does not 
> fully work with the JSON rendering. No big issues a client would be 
> affected by but enough that I cannot use it as a basis for the JSON 
> rendering spec.
>
> If people do not disagree I would be glad to create a clean "OCCI HTTP 
> Protocol" doc totally free of any payload or header rendering data 
> formats. Then the JSON and text/xxx renderings could be built on top 
> of it. I.e. a clean separation between data format and protocol. We 
> could call it occi/1.2 and have it backward compatible with occi/1.1. 
> Any objections to that? ;)
>
>> Besides that, there is no reason forcing to use JSON over HTTP, if 
>> they don't want to: replacing the "href" by an URI (and maybe 
>> renaming it to "location" would allow for broader use of the JSON 
>> data rendering; and everything else is pretty agnostic of HTTP and 
>> friends.
>
> Ok, renaming "href" back to "uri" then. Good proof you actually read 
> the details :D
> (mind-note to add other small obscure changes in next rev just to see 
> if people notice...)
>
> What to call the category identifier? I used "rel" now based on the 
> HTTP way of doing things. Any better naming suggestions, "type" ? [1]

A little perspective on 'rel'. This is an artifact based on the HTML5 
and RDFa rendering that haven't yet matured.  I would suggest we keep 
the 'rel' in case the there is a huge shift to semantic  approaches for 
cloud computing.

>
>> And btw.: HTTP gives us all we need to do the protocol part; the 
>> RESTfulness lies in there, anyway. Therefore, the interaction part 
>> should be described there, agnostic of the content-type (after all, 
>> that's what HTTP is about). That way, people could implement the HTTP 
>> protocol rendering once, and reuse it for several OCCI data renderings.
>
> Agreed on that. Support my proposal on an OCCI HTTP Protocol doc above :)
>
>>> - Try to make the single-instance format more lightweight and not 
>>> duplicating any information available through the discovery 
>>> interface. Thanks Jamie.
>>
>> That actually I like very much. It might be nice to think about a 
>> shallow/deep rendering option on the protocol level, but that's just 
>> a thought.
>
> If you are referring to all the white-space in the examples it is just 
> there for readability. I should put in a note that a server/client 
> should remove all unnecessary white-space for real communication.
>
> If not, please elaborate.

I'm interested in this as well.

>
>>> - Use the "marker" concept from OpenStack for pagination as 
>>> suggested by Andy.
>>
>> This is also something that should be taken care of in the protocol, 
>> rather than the data format. Why on earth would people want to see 
>> this if the protocol they use only delivers batches of things? And in 
>> fact, looking at the spec, it has been done on the HTTP level, anyway.
>
> It is done both on the HTTP level (query parameters) and in the 
> payload :-\
>
> Is it just the "next" and "limit" members you want removed from the 
> collection format? Anything else you deem to be protocol stuff?
>
> I guess we could put the "next" link in a Link header and actually use 
> RFC5988 as it was meant to be used (as opposed to how we abused it in 
> text/occi rendering). We have to verify if browsers would choke on 
> this though and it makes life a bit harder for JavaScript 
> implementations which would need to parse the Link headers. Other ideas?
>
This is a query capability and should not be part of any portion of the 
format or http protocol.

I think there is some confusion about document structure and 
presentation with the occi model. Granted, this has been clearly vetted 
withing the group.  We should keep this discussion in terms of a query. 
The "marker" as suggested is essentially acting as an arbitrary index or 
iteration context in application.  We should be clear on the use cases 
and whether the "marker/iterator'  applies to occi entities, json 
entities and payload size. There are very separate concerns that seem to 
be getting integrated as some levels.

>> Frankly, this should be something to be added to the HTTP protocol 
>> rendering and made available to all data representations, rather than 
>> in a proprietary, JSON-specific way only.
>
> Agreed, with reservation for possible browser problems...
>
>>> - "range" and "default" attribute properties as requested by Florian.
>>
>> Great idea. We might want to consider pushing this upstream to core.
>
> That was my intention. I have long wanted to have the "default" 
> property into Core since without it a client cannot create custom 
> templates.
>
> Thanks for the feedback Alex. More of this and we might have something 
> to publish in not a too distant future.
>
> /Ralf
>
> [1] http://martinfowler.com/bliki/TwoHardThings.html
> _______________________________________________
> occi-wg mailing list
> occi-wg at ogf.org
> https://www.ogf.org/mailman/listinfo/occi-wg