Eduard Moraru wrote:
> Sorry for the typo. (loose -> lose)
>
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.
> Could we also need the selectors(as I earlier mentioned but probably did
> not get noticed):
> - All objects of the class {className} in a {page}, {page}'s {version}
> or the entire wiki?
>
> /objects/class/{className}/
>
This could be indeed useful, but maybe we don't really need it, do we?
Do you have an use case for this?
> /space/{space}/page/{page}/objects/{className}/
>
> /space/{space}/page/{page}/history/{version}/objects/{className}/
>
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/
_______________________________________________
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
