Comments before proceeding with spec

[Jens Hübel <jhuebel@opentext.com>]

HI all,

 

thinking about dividing our work to make more progress I wonder if we should agree on certain design principles and building blocks to avoid that every service looks different.

 

I looked a bit at the critics we have received in the past and how we designed the AtomPub protocol. I came to the conclusion that I would try to identify resource and then http methods, requests and response formats. I would use thoise to define URL naming and query parameters. This would be more a  RESTful way in contrast to start from the services in the domain model. No doubt that in the end we need both to be sure that we can map the entire CMIS domain model to the browser binding.

 

I think CMIS resources come in three flavors: simple entries, collections (or lists) and hierarchies. Some resources exist on its own (e.g. document, policy) and have an id. Some resources exist only in context of other resources (e.g. parent, rendition, content stream).

 

If we define schema definitions for basic resources, and design (or composition) patterns for collections and hierarchies as building blocks for the JSON schema we could achieve a certain consistency between the domain model services.

 

Talking about and identifying resources would also help us to compare the existing proposal for URL patterns (http://tools.oasis-open.org/issues/browse/CMIS-677) to other possible approaches.

 

I would also like to see if we could somehow document important design decisions. For example whether we define the JSON binding in a RESTful way or in  non RESTful way is something that needs an agreement within the group and this decision should be documented. I also think the initial goals we discussed (less chattier than AtomPub, more browser friendly, reduce number of roundtrips for typical use cases, less expensive responses for a server) should be written down somewhere so that we can refer to them in the technical discussions.

 

A couple of things popped up in the last call that needs (at least for me) further clarification and discussion:

Why is a (more) RESTful design inappropriate for our purpose? Is this per se a contradiction to browser-friendly?

If we have certain issues in specific environments (like JavaScript libraries) or escaping issues with id syntax we carefully should evaluate how much this should impact our overall design or if we can find solutions or workarounds for these specific cases.

 

In no way I want to insist on a pure (or “religious” REST design), but I want to make sure that we get what we need. And these questions came up looking on the existing proposal.

 

Let me know what you think and let us try to make more use of the mailing list in addition to the conf calls for the discussions we need.

 

Jens