Re: [xwiki-devs] [RFC] RESTful API

Dear all, we had some comments from Jerome Louvel (the author of Restlet). I will summarize them here FYI. Things in double square brackets are comments of mine. 1) Use more specific variable names in URI templates (e.g., spaceId, pageId, etc.) [[Already updated on the wiki page]] 2) Use ';' instead of ',' as a separator since it complies better with the definition of URI matrix by Tim Berners Lee [[Already updated on the wiki page]] 3) /watchlist seems a strange resource. Isn't it associated to a user? If yes this should be made explicit like "/accounts/{accountId}/watchlist[?start=offset&number=n]" [[Right. However I was implicitly supposing that every request provides authentication info (guest included). So basically the user is implicitly given at every request in a header]]

4) Content negotiation via suffixes is transparently supported by Restlet through the TunnelService 5) The second proposal seems to be more simple. If the version is not specified in query parameters, it is expected to be the latest one. This should be precised. [[Already updated on the wiki page]] [[I am collecting some more info about the second proposal. I started also a discussion on the REST discussion group in order to have more feedback]] 6) Representation description is missing. [[Working on it, see previous mails]] 7) Think about WADL for describing the API in a dynamic way. Restlet supports the automatic generation of a java-doc like documentation of the API through Yahoo! XSLT. [[I am investigating it]] Thanks to Jerome for his precious comments. -Fabio