[Ocs] [rant] comments on open-collaboration-services

[Thomas Koch]

Hi,

I'm writing my bachelor thesis on REST and person/contact information[1]. By 
incident (via Enrico Zini's Talk on Debconf11 about app installers) I found 
open collaboration services, which also contains person informations and the 
common wrong claim to be restful.

Since I care about free software I dare to give a few comments from my first 
impression. I'm sorry if I should get anything wrong.

a) OCS is not restful for several reasons[2], e.g.:
  - predefined URIs (templates) instead of discoverability
  - no reuse of existing media types (see below)
  - meta data in the body instead of in the header
  - GET/POST/PUT and DELETE are already specified in REST (HTTP). Respecifying 
them means either that they're misused or that the specification is redundant.
  - "URL arguments" are a very good indicator of a non restful RPC-over-HTTP 
like API. An URI is an identifier, not a place to put procedural parameters. 
The method is GET and it has one required parameter: the URI. Several other 
optional parameters are specified in the HTTP request header.

b) Use descriptive tokens instead of (or additional to) numbers (type, status, 
...). The extra bytes are well invested to ease development and 
"debuggability".

c) Reuse existing HTTP status codes and don't blow your specification by 
reiterating things that are already specified elsewhere.

d) Reuse existing standards and media types. Candidates could be:
vCard/xCard, Activitystreams, ATOM especially ATOM categories, iCal Events, 
oAuth2, oStatus

e) It's especially sad, that there was another attempt to represent person 
data inside freedesktop which also didn't look for existing standards:
http://groups.google.com/group/desktop-
couchdb/browse_thread/thread/4dbac2e9d03aaa5d

There may be other standards that I'm not aware of for example to declare 
dependencies between software, maybe here?
http://open-services.net/
http://en.wikipedia.org/wiki/Description_of_a_Project

OpenSocial is similar in some regards but also a non restful standard and 
shouldn't be taken as a model. But at least it is supported by major companies 
and still has an open process. It is an example that even Yahoo, Google, IBM 
and others can produce bad standards.

[1] https://github.com/thkoch2001/bachelor-thesis
[2] http://kellabyte.com/2011/09/04/clarifying-rest/

Regards,

Thomas Koch, http://www.koch.ro