[Ocs] Some notes on OCS specification
spillner at kde.org
Sat Mar 26 03:59:10 PDT 2011
Hello from the Blue Wonder sprint . 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
* 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
* 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.
More information about the Ocs