On Dec 15, 2008, at 5:24 PM, Fabio Mancinelli wrote: Not yet but we want to support this in the future yes so better design a REST API that will work with nested spaces (arbitrary level yes). Thanks -Vincent

Artem Melentyev wrote: Yes, but this might lead to ambiguities in URI routing. Consider /tags/foo Is it a a list of pages tagged as foo, or the foo page in the tags space? By interleaving variable parts with fixed ones this ambiguity can be solved. This is standard practice however. Even the plural form. But this can be worked out I guess. This was a leftover of the current implementation. Actually we can get rid of this resource. I am not sure what Alexandru's implementation returned but I guess it was the {space}.WebHome page. Propbably you missed it. It's already there. Again a leftover of the current implementation. Anyway I agree. Thanks -Fabio

Artem Melentyev wrote: +1 I'm not sure... 'history' is semantically more correct than 'versions', IMO, at least for me. Versions is closer to variants than to history (see http://wordnetweb.princeton.edu/perl/webwn?s=version ). It might even lead the user to think of translations. -- Sergiu Dumitriu http://purl.org/net/sergiu/

On Dec 15, 2008, at 6:51 PM, Sergiu Dumitriu wrote: +1 to that. -Vincent

Other question: Why use the plural when retrieving a single instance. For example: /spaces --> All spaces /space/{space} --> One space Ah just saw you changed that but not everywhere. Like classes/{class} should be class/{class} And pages/{page} should be page/{page} no? Re nested spaces the best is probably to define a delimiter other than "/" Something like: /space/this::is::nested/page/WebHome Of course this would mean that "::" is not allowed in space names. BTW this would also means that "/" is not allowed in space names. -Vincent On Dec 15, 2008, at 5:39 PM, Fabio Mancinelli wrote:

Vincent Massol wrote: Actually I think that the plural form makes sense. /spaces/Main means that in the "list of spaces, I want the Main space", being /spaces the resource representing that list. Same thing for classes. -Fabio

Vincent Massol wrote: It is currently, so dropping it would be a regression. %2F can be used to escape / inside the space/page name. -- Sergiu Dumitriu http://purl.org/net/sergiu/

Vincent Massol wrote: +1. We use an identifier for every sub-fragment of information to eliminate the URL-parsing magic. The more information -> The less ambiguities -> The simpler things are. Plus, /spaces/Main/pages/WebHome/2.3 does not suggest that 2.3 is a version. More, like with version control systems, in the future I'd like to add support for version tags, which would be accessible using: /spaces/{space}/pages/{page}/history/HEAD /spaces/{space}/pages/{page}/history/some_tag If we don't use /history/, there will be more if-else programming and more reserved keywords. That's one of the reasons why I insisted on /spaces/{space}/pages/{page}/ instead of /{space}/{page}/ . Here {space} can be a nested space, for example: /spaces/A/Nested/Space/pages/Page/ Drawback: a space hierarchy cannot have a part named 'pages' (or other special names). Alternative: Use %2F as the internal separator, like: /spaces/A%2FNested%2FSpace/pages/Page/ Possible problem: %2F causes Tomcat (with the default settings) to abort the request, since there are some security problems with poorly designed applications. Another problem: This will be incompatible with the current URLs, since %2F is used to escape / inside space or page names. This URL works quite well: http://localhost:8080/xwiki/bin/view/Blog%2F2.0/Here%2Fwe%2Fgo , where the space is Blog/2.0 and the document is Here/we/go So, I'd like to stay with: /spaces/A/Nested/Space with %2F in it/pages/Page with %2F in it/ How about some of the views done in WebDAV, like attachments view and tree view? /attachments/spaces/{space}/pages/{page}/{attachment.ext} I'm not sure about the extension-controlled format. What if the document contains dots in its name, like "Help/How to create a .pdf"? More URL-parsing magic? And then what about "How to open a .tar".gz versus "How to open a .tar.gz"? I think that HTTP Accept header alone is better. To make XMLs more friendly, we could use XSLT stylesheets to transform them into HTML on the client. /space/{space}/pages/{page}/objects/{id} -> what is the id? How to handle both new GUIDs and old indexes? I prefer to also have the detailed property view. -- Sergiu Dumitriu http://purl.org/net/sergiu/

Fabio Mancinelli wrote: Sorry, I meant prefix. -Fabio

Luis Arias wrote: I don't think it can be done, as HTTP servers and clients usually don't allow other verbs to be used. -- Sergiu Dumitriu http://purl.org/net/sergiu/

On Dec 16, 2008, at 10:50 AM, Eduard Moraru wrote: [snip] I think I agree (need to think more of consequences). Probably historical reason. Attachments have a separate store but we could generalize this to let objects have an optional separate store too. Something to keep in mind when we redesign the model. Ludovic, any input from you on this? Thanks -Vincent

Eduard Moraru wrote: Of course objects are enough to handle them but since comments and tags are very "useful" objects imho it's worth to expose them *also* as separate resources that can accept specific media types. I mean, imagine you want to tag a page. If you have /spaces/{space}/pages/{page}/tags You can do a POST to that URI by sending, for example, just the new tag. Something like: curl -d "foo" http://localhost:8080/spaces/Main/pages/WebHome/tags If you handle this *only* with objects you will need to post a more complex media type, typically an XML containing the property name, value, etc. Same thing for comments: curl -d "I like this page" http://localhost:8080/spaces/Main/pages/WebHome/comments I agree that with guid the old way of identifying objects is useless. I put it in the resource list because it is the current way of identifying objects. And maybe somebody has a reason to leave it. I don't understand why you say we "loose". If we want to expose a /tags resource we can do this. And I think that it's a resource worth to be exposed. Probably for indexing purposes that could be useful. AFAIK, it's for historical reason. Yesterday I was asking ThomasM how attachments work because me too I found it a bit counterintuitive. Thanks. -Fabio

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/

Vincent Massol wrote: Actually I think you're right. I checked the "URI design" section of the Restful Web Services book, they suggest to "use query variables only to suggest arguments being plugged into an algorithm" (e.g., Google search "q" parameter) So, since a "page" doesn't seem to be an algorithm, I think the second proposal is not in line with the "good practices". Never mind. Thanks. -Fabio

Sergiu Dumitriu wrote: Not sure about this... At the protocol level, AFAIK, query parameters are part of the URI an though they contribute to identify the resource. So, at this level, imho, it is almost a philosophical or best practice matter. Anyway I thought again about query parameters and actually the main reason why they are problematic is because apparently many caching agents, by default, don't take into account query parameters. Squid, for example, does so (but it can cache resources by using the full URI http://foo/bar?param=value if configured properly). So if we want to be sure that caching occurs, maybe it's best to identify cacheable resources without using query parameters. -Fabio

On Dec 24, 2008, at 3:55 AM, Sergiu Dumitriu wrote: +1 to that. -Vincent

Sergiu Dumitriu wrote: The ultimate validation is Roy Fielding's thesis. Anyway, I am not against what we have said. What I would like to avoid is to build a so called RESTful Api that is not RESTful and that would be criticized as this API http://wikis.glassfish.org/socialsite/Wiki.jsp?page=FinalizeRESTAPI in this post http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven I am +1 about this, don't misunderstand me. Now the problem is to use these URI in a proper RESTful context. Well conceived media types and hypermedia leverage is the biggest challenge now. -Fabio

Paul Libbrecht wrote: Yes, read all of it someday in the past. Anyway the "hypermedia as the engine of application state" has been a recent hot-topic of the REST community since when Fielding did the post I cited in my previous mail. Recently a very nice article has been published on InfoQ about the subject: http://www.infoq.com/articles/subbu-allamaraju-rest I have linked all the references I have cited on the XWiki page about the RESTful API design on Xwiki.org for keeping track of the background discussion. Thanks. -Fabio

On Dec 19, 2008, at 5:41 PM, Fabio Mancinelli wrote: Does this mean I cannot open my browser and call the REST URL without specifying a user? Thanks -Vincent

On Dec 19, 2008, at 6:27 PM, Fabio Mancinelli wrote: Is that right? It sounds cumbersome and bad for easy automation when you want guest access. Cannot we default to guest when no username/account is specified? Thanks -Vincent

On Dec 19, 2008, at 6:57 PM, Fabio Mancinelli wrote: I have the feeling that REST services that I have used in the past don't do this. For ex I can open a browser and type: http://repository.sonatype.org/service/local/repositories And it just gives me the answer without having to type anything. See the Authentication section of https://docs.sonatype.com/display/Nx/Nexus+Rest+API I really prefer it this way. We need to make it extra easy to query IMO (for open wikis). Thanks -Vincent

Vincent Massol wrote: Because resources are not restricted and they can be browsed as "guest". Even there they state that "A user may be authenticated by providing their credentials to /authentication/login OR to any restricted resource in the form of HTTP Basic formatted data in the Authorization HTTP header of the request. The response will include the authToken as a value in the data response to the request." Now since in our case, imho, every resource can be considered "restricted" (starting from the space list, because its representation depends on the actual user requesting it) this boils down to what I was saying. But the link you provided contains an interesting alternative! (To be verified) We could provide a /authentication resource which provides a challenge for plain browser users. So basically if the user requests a resource, it will always be served as if he were guest. In order to access to the "restricted" representation it must before visit the /authentication and provide credentials (through the popup). Then he could visit other resources that will be server by taking into account the auth header that the browser (hopefully) sends. The only concern is whether the browser, after the authentication, sends at each subsequent request to the site the auth header. Of course here I am speaking only about an interaction with a plain browser. Anyway this is an important aspect that must be discusses in depth. Others, WDYT? -Fabio

Sergiu Dumitriu wrote: I have looked at https://docs.sonatype.com/display/Nx/Nexus+Rest+API and, in the authentication section they state: GET - /authentication/logout - Expire an authToken Authorization Header This is completely UNRestFul, since it subvert the semantics of the GET verb (safe and idempotent), and it encodes in the URI an operation and not a resource. I am -1 for this. -Fabio

Vincent Massol wrote: Maybe there was a misunderstanding. I agree with you. I just didn't agree with the way Nexus does it. Anyway I committed a tentative implementation of the behavior you were suggesting in the sandbox. -Fabio

Hello, Looking at the proposal again, I feel it has a very document oriented perspective and does not do justice to the primary use case of a wiki which is collaborative work. So for instance, a user is not viewed as a resource. That means that if I want to know what a user's recent activity on a space that we share, well it would probably require some processing with the current api. I would have liked to have done something like a GET on /users/{userId}/spaces/{spaceId}/recent Anyhow that is a real common use case, who has done what on a shared work space. The notion of a group of users is also missing so it wouldn't be so simple to let's say to have a client that allows me to send an email to my group. Whereas something like getting /groups/{groupId} would probably be quite sufficient, another common use case. Finally, since some of this might seem useful for these basic elements, it might also be useful for XWiki classes in general to be able to expose a bit of RESTful api. So let's say I implemented a friends feature by linking user objects, I would certainly like to expose something like a GET on /users/{userId}/friends So I think one of the requirements in the design is to allow this type of behavior, maybe by linking a script to an object that describes the api and is attached to the XWiki class. More thoughts... -- Luis Arias +33 6 14 20 87 93 skype : kaaloo

Pascal Voitot wrote: Right. A way to do authentication is the way Google does. You post your credentials to /authorization and you get as a response a token that you provide in subsequent request with an Authorization header. The POST operation could also generate a URI that you will DELETE in order to logout. Or you can also put a timeout on the token so you don't have to logout at all. The problem here is that, while this is perfectly RESTful, it's not very practical to do with a plain browser because, unless you do some javascript magic, you cannot add headers to a request just by typing something in the URL bar. A solution could be as other suggested to use the http://username:password@uri in order to leverage Basic auth, or as I proposed to expose a special uri that when requested challenges the browser to ask for an authentication. Subsequent requests will have the Authorization header set and, hence, login performed. -Fabio

On Mon, Dec 22, 2008 at 10:56 AM, Eduard Moraru &lt;eduard.moraru(a)xwiki.com&gt;wrote;wrote: User as a resource seems quite logical... this is the same point of view as OpenID... for security issues, passing the user/password for each request is really not very good... I really prefer the authentication token approach...

On Mon, Dec 22, 2008 at 12:14 PM, Eduard Moraru &lt;eduard.moraru(a)xwiki.com&gt;wrote;wrote: For sure, but it enforces the hacker to be just a bit more clever... But you're right!!! Basic and Digest authentication is a bit light :) We should do as Amazon S3 and define our own Authentication digest called AWS ;););) Don't know if this is really needed... Currently, without REST, XWiki doesn't use HTTPS and has the same authentication risk, am I right? But if we want a strong security layer, HTTPS could be a solution...

On Mon, Dec 22, 2008 at 2:50 PM, Sergiu Dumitriu &lt;sergiu(a)xwiki.com&gt; wrote: I was joking :) Basic auth will be good enough :) +1 for this... and even HTTPS can be attacked :)

Eduard Moraru wrote: +1 for URL authentication. This is something needed (for command line clients that don't speak BASIC auth), although it is not safe at all. Still, it has the same safety level as BASIC auth, so it is no less safe than other authentication methods (given that by default our login sends plaintext values over HTTP). -1. Although URL authentication should not create any persistent authentication, we need something persistent (using cookies). -- Sergiu Dumitriu http://purl.org/net/sergiu/