[Ocs] Some notes on OCS specification

[Josef Spillner]

Hello from the Blue Wonder sprint [0]. Our discussions here in Dresden include 
aspects of social gaming. I've had a look at the OCS v1.6 API specification as 
one of the results of our brainstorming.

Some impressions I've got from the specification:

* It doesn't tell anything about the MIME types of the content served. My 
suggestion is to mandate one, for example application/ocs+xml and 
application/ocs+json.

* Likewise, it doesn't mention HTTP status codes. My suggestion is to mandate 
200 for "status code 100" and 4xx/5xx for all others. Reading the archives, 
Cornelius already mentioned some sort of unnecessary redundancy in the 
achievements extension but IMHO this issue applies to the core API as well, 
such as code 102 - login not valid for person checks.

* There are some arbitrary limits like a maximum of 1000 records. Such limits 
should be implementation-dependent and moved from the normative section to a 
guidelines section similar to how SSL (or rather TLS) is recommended.

* The method names are not at all intuitive. For example, /config is a top-
level method but has a "config" heading and a "config" subheading in the 
specification. For /person, the /data submethod is called "search" in the 
subheading.

* Some response structures are rather long already, for example regarding 
<favouritefoo> in person objects. And they will likely become longer, for 
example once <team>s a person is part of are added to this information (just 
one scenario I had in mind). Perhaps it would be useful to slightly add some 
complexity in order to reduce length, for example, have <homepages> and 
similar groupings for elements which can appear multiple times instead of 
<homepage1>, <homepage2> etc.

* The response messages are not well documented. What does 
<privacy>1</privacy> mean? Which detail levels exist for <person> other than 
"full" and how to specify them? etc.

* The examples list URLs such as http://user:password@... which contradict the 
recommendation to use SSL.

* The OCS website should be extended with more concrete information about 
server and client implementations and which OCS services they support, and the 
spec should refer to this list.

Eventually, the spec should receive external reviews to make it more clear and 
unambiguous and thus more useful for implementers. There are also several 
spelling errors like usefull, successfull etc.

Josef

[0] http://community.kde.org/KDE_Games/Sprint_2011