Re: [xwiki-devs] [RFC] RESTful API + Media types

Eduard Moraru wrote: Actually it was not for the typo (I read it as "lose" anyway) but for the overall meaning. As I replied earlier, I don't understand why you said that we could lose /tags as a drawback... If we want it to be there we just put it there :) And I think that's a good resource to have. This could be indeed useful, but maybe we don't really need it, do we? Do you have an use case for this? Yes, they are missing. Now that we have spent some time thinking to URI design, the next phase is to start thinking about media types design which, imho, is even more important. A remark here... Having these URI is good because they are meaningful and clients can guess. However the RESTful API should be, above all, hypermedia driven by what clients receive as a result of their requests (i.e., the media types). So for example the "discovery" of the available resources (whatever is their URI) should be made by following links and by interpreting media types. Infact, if we hard-code those URI in a client we just end up with a pseudo-XMLRPC api that uses HTTP as its semantics and custom media types for request/response. Moreover we increase the coupling between the client and the server (in case one day we decide that a given URI is not anymore appropriate). Not very RESTful[1] Fielding in [1] says, besides other interesting things, that "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark)" This is what happens, for example, with Atom Service documents that are the "entry point" for all atom collections. Clients are then driven by the media type representing those collection till the "edit URI" of an entry for updating its content. So I was thinking that rooted at the toplevel / there should be a "service document". Something like: <xwiki> <link rel="spaces" href="spaces"/> <link rel="tags" href="tags"/> <link rel="watchlist" href="watchlist"/> </xwiki> These elements will give the URIs to the toplevel hierarchy for discovering all the rest. A thing to be noted here is that URIs are generated by the server that has full control of its own "namespace". What is important here is the semantics of the rel elements. Following the same principle documents served at a given URI should be rich in terms of links (properly "annotated" with rel-like attibutes) in order to allow clients to "discover" more resources. What is important is that we establish a good semantic model and a good set of elements in media types so that clients can understand what they receive. Of course the set of the available elements can be extended in the future. Old clients will still be able to understand what is server (they will ignore new items). New clients will be able to take full advantage of the new exposed resources. This is what happens with the GData extension. Basically Google is using Atom + GData extensions in order to provide resource representations. A plain Atom client is still able to understand what is "available"... But, for example, it will miss the geolocation of the different items! The same principle should drive, imho, our media types. Maybe we could also rely on Atom[2] as well as the foundation for our media types. Anyway looking at the Atom Syndication Format[3] and the Atom Publishing Protocol[4][5] and above all at its mechanism for specifying metadata and links to actual data could be very useful in order to design a useful and a good RESTful API. My 2 cents. -Fabio [1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven [2] http://abdera.apache.org/ [3] http://www.ietf.org/rfc/rfc4287.txt [4] http://www.ietf.org/rfc/rfc5023.txt [5] http://www-128.ibm.com/developerworks/library/x-atompp1/