[Ocs] Some notes on OCS specification

[Frank Karlitschek]

Hi Josef,

thanks for the good feedback.
I think I agree with all of your points.

I think we should merge your suggestions into version 2.0 of the spec.

I hope we can do this during the OCS sprint.

Cheers
Frank


On 26.03.2011, at 03:59, Josef Spillner wrote:

> 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
> _______________________________________________
> Ocs mailing list
> Ocs at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/ocs


--
Frank Karlitschek
karlitschek at kde.org