[iks-community] Some guidelines to document API of RESTful services

[Olivier Grisel]

Hello,

During the architecture meetings of the IKS Workshop there was a
consensus to allow the CMS to access the IKS services through a
RESTful API. To document such APIs we can the Twitter API
documentation as reference :

  http://apiwiki.twitter.com/Twitter-API-Documentation

For each method, we give the:

- the query URL pattern
- the HTTP method (GET, POST or even PUT, DELETE, ...)
- the URL arguments with type info and human readable descriptions
- the accepted media types of the payload (JSON, XML, RDF-XML, N3,
binaries, ...)
- a schema for the payloads (XSD, RDFS, ...)
- a sample query with sample expected result (optional but really
helpful to get a quick grasp)

I think it is also a good practice to offer a sample HTML / Javascript
application as a demo client for the service. The reusable parts of
the demo application can be packaged as a reference javascript SDK.
The jquery library and plugins can really help for this.

The public Zemanta API is also a good example of such RESTful API documentation:

  http://developer.zemanta.com/docs

However, there is a problem with this API: the URL is always the same
and the "verb" of the method is passed as a JSON keyword arguments.
This is not really in the spirit of RESTful APIs and it would be nicer
to make the method name explicit in the URL pattern as twitter does.

On the implementation side, the recommended way to implement RESTful
services in the Java world is to use a standard JAX-RS library such as
the open source reference implementation jersey:
https://jersey.dev.java.net/ (google for "jaxrs tutorial" and you will
get quickstart references such as
http://www.myeclipseide.com/documentation/quickstarts/webservices_rest/ ).

Also, the RESTful API documentation can be complemented with the
documentation of the native underlying implementation, at the library
level. Eg. in the case of java implementation, the Javadoc of the
public Java interfaces.

To get the global view of all the services of the stack, tools such as
SCA can be used but in my opinion a single wiki page for each RESTful
service + a toplevel wikipage that summarizes the list of services
with an arrow / blob diagram as global overview is good enough and
simple for everyone to contribute without having to learn new tools.

Best,

-- 
Olivier