[Ocs] Some notes on OCS specification

Sun Apr 3 11:12:23 PDT 2011

> 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.

I have been told by Josef on IRC about this, thus I am just posting those words
here, now, in order to not lose that information:
"Both MIME type and, in the case of XML, the namespace specification are best
practice rules, to be precise, the MIME type should be application/x-ocs+xml
because it isn't officially registered yet"
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1

> * 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.

'4xx for user needs to do something or 5xx for server-side errors' makes sense
to me. :)

> * 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.

I agree also about that, it would result in a more abstract API. (I also had
issues about it, like previewImage limitation). The concrete numbers
could vary on the implementation level and the recommendation could also be
avoided then in the specification. (Maybe a maxrecord, maxpreviewimage-like tag
and external wiki page for the conventional list usages ?)

> * 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.

That is true, there are other situations like that (for example):
Syntax: /v1/person/add for adding a person, but Syntax: /v1/knowledgebase/data/
for adding a knowledgebase entry.
Considering that 'Syntax: v1/content/add', 'Syntax: /v1/fan/add/"contentid"'
'Syntax: v1/event/add', 'Syntax:
/v1/comments/data/"type"/"contentid"/"contentid2"'
etc.

> * 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.

Good idea because it can be much cleaner and more readable then. (like service
container, services).

Furthermore:
 <data>
  <homepagetypes>
   <id>0</id>
   <name>&amp;nbsp;</name>
  </homepagetypes>
  <homepagetypes>
   <id>10</id>
   <name>Blog</name>
  </homepagetypes>
  <homepagetypes>
   <id>20</id>
   <name>Facebook</name>
  </homepagetypes>
 </data>

It might be better to use an outer container with plural form and not plural
text for the each element.  (The situation is the same with dependtypes, plural
is used for each single element)

It is fine in case <ircchannels>kde-dev, plasma</ircchannels>, but those
elements contain one data entry.

It is generally a better idea to use XML structuring (XML-Schema complexType)
and not comma- or space-separated lists (XML-Schema list) because it makes the
parsing easier, but it also creates more traffic.  If we make the 2.0 as
planned, it is better to change for XML structure, yes :)

> * The response messages are not well documented. What does
> <privacy>1</privacy> mean?

Yes, it would be nice to have it documented.

My impression is that there could also be some more meaningful texts
occasionally, like this:

<description>How can I 22........</description>
<subject>Re: jjjjjjjjjjjjjjj</subject>
 <subject>vxvdfvd</subject>
<text>gfdgfdgfgfgf
<subject>vfvvdsx</subject>
<text>vdxvvsx</text>
<name>yheweq</name>

Some text referring to the content where it is involved could be more useful
and pleasant.

> Which detail levels exist for <person> other than "full" and how to specify them? etc.

<person details="check">
<person details="summary">
<person details="full">
<person details="balance">
<person details="fans">

That is what I have just figured out. No explicit documentation, thus you can
have some guess-work, but it might well be better to mention them explicitely in
the documentation sections, yes :)

The problem is more like that you do not know what else you can use, I guess,
maybe not just one, but more in a given case. It would be easier to figure
out what it expects if it is not that what is mentioned in the example, but
can also be something else.

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

https makes sense to me. :-)

> * 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.

Yes, that would be useful. I guess it was a lack of time.
What I can see in the specification is the KDE provider file reference:
The KDE provider file is here: http://download.kde.org/ocs/providers.xml
(Which is a bit outdated since the comment service is an important one for
example)

Josef mentioned this one as an example on IRC:
http://ghns.freedesktop.org/

What would also be useful is if the OCS specification versions tagged could be
seen properly. To have a main page where the user can select any previous or
current OCS specification version for a view:
(maybe here: http://www.freedesktop.org/wiki/Specifications ?)

The version 1.5 is available here, but the previous versions:
http://www.freedesktop.org/wiki/Specifications/open-collaboration-services-1.5
1) There is no list where all the versions are mentioned
2) 1.3, 1.4 etc cannot be found. (1.5 -> 1.x change in the URL does not work)

Differences can be seen here, that is nice.
http://www.freedesktop.org/wiki/Specifications/open-collaboration-services-draft?action=diff

> 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.

Furthermore:
http://www.freedesktop.org/wiki/Specifications/open-collaboration-services-draft#Services
This part of the specification does not mention the services involved in this
document.

I have just fixed some spelling errors like that. I also corrected the
formatting issues in case the achivement module in order to make it more human
readable. =)

It would really be awesome if more people could take a look at it. It might
well be the OCS 2.0 sprint then in Berlin as a first, but big step. :-)

Best Regards,
Laszlo Papp