On Wed, 29 Feb 2012 09:36:50 +0100, <alexander.papaspyrou@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