[occi-wg] JSON Rendering proposal, rev 2

[Ralf Nyren]

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

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

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

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

> 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