[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Randall Hauch commented on DNA-309: ----------------------------------- The most obvious first approach for a URI design is to directly represent each node in the repository as a resource, and to map the repository operations to GET (read), PUT (update/create), POST (create), and DELETE (delete). For example, "/a/b/c/d" would identify the node "/a/b/c/d". A "GET /a/b/c/d" request would obtain a representation of the "/a/b/c/d" node. Perhaps the first challenge to this approach is whether to also treat properties as resources. If each property were treated as a resource, then the URI design would have to distinguish a node property named the same as a that of a child of the same node. For example, if a node /a/b/c in the previous example contained a child "d" and a property "d", then is "/a/b/c/d" referring to the node or the property? One option is to distinguish properties with a character ('@' comes to mind), although which character would depend on URL escaping requirements. It probably is possible to require this character only when there is a child with the same name as a property name (something that is not too frequent, I expect). The kind of resource to return (e.g., JSON, XML, HTML, etc.) should be driven by the "accept" HTTP header, which specifies the media ranges (mime types with optional parameters) that are being requested. Multiple mime types can be specified, with precedence rules and quality factor denoting the preferred order. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html By using the HTTP header, the URI no longer needs to deal with extensions or any other mechanism to denote the desired response format. And this means that the URI design can more closely match the resource names. Here's an example of a GET request to obtain a JSON representation of node "/a/b/c/d": GET /a/b/c/d Host: myhost.example.com Accept: application/json URI query parameters are useful to supply additional criteria and information about the representation to be returned, such as depth of the representation or reading just the properties or children. This seems to be an acceptable way of affecting the representation. What about operations, like move or copy? One choice is to use query parameters (e.g., PUT with a "?moveTo=/a/b/e" or POST with a "?copyOf=/a/b/e"). Another option would be to allow actions or operations in the representation that is PUT by the client. The following example is an HTTP request to move node "/a/b/c/d" to "/a/b/e" and simultaneously set the "jcr:title" property to "This is a new title": PUT /a/b/c/d Host: host.example.com Accept: application/json Content-Length: nnn Content-Type: application/json { "dna-action:moveTo": "/a/b/e" "jcr:title" : "This is the new title" } -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Randall Hauch commented on DNA-309: ----------------------------------- The URI design may need to make room for different repositories, workspaces, etc. The first segment of the URI (below the host or application URI) might specify the repository name, the second the workspace name, followed by the path to the node. For example: /repoA/myWorkspace/a/b/c/d would identify the node "/a/b/c/d" in the "myWorkspace" workspace of the "repoA" repository configured by the RESTful server. What about searching? Well, search could be done using the "/search" URI, making that a reserved name and unusable for the repository name in the configuration. That probably is pretty acceptable. What about a web application for users to view, navigate, edit the content through a browser? Well, its quite likely that this application would be in a different WAR (perhaps still deployed to the same server). However, there are two options if the web app is to be in the same WAR file: reserve the "/ui" URI for this (might be a good idea anyway), or simply use the HTTP accept header to specify that a client wants the (probably rich) HTML for a resource. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Randall Hauch commented on DNA-309: ----------------------------------- Here is an open source project that provides a web application that can respond to RESTful requests by accessing a JCR applications: http://code.google.com/p/jc-rest/ At the moment it doesn't appear to support updates, but it would be interesting to see the kind of REST operations it expects. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Randall Hauch updated DNA-309: ------------------------------ Summary: Design URLs and rerepresentations, leaving room for future UI features and maybe WebDAV (was: Design URLs, leaving room for future UI features and maybe WebDAV) -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Randall Hauch commented on DNA-309: ----------------------------------- Another interesting discussion regarding the Sun Cloud API (Tim Bray) and responses (including Roy Fielding): http://www.infoq.com/news/2009/04/post-state-appropriate -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Brian Carothers commented on DNA-309: ------------------------------------- I opened a forum topic on the subject. I do believe that we would want to avoid the namespace overlap issue by mounting the RESTful piece under /resources. This would leave room for /webdav, /ui, /soap, or anything else in the future. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Randall Hauch commented on DNA-309: ----------------------------------- Another interesting article describing some suggestions for designing RESTful APIs: http://blog.feedly.com/2009/05/06/best-practices-for-building-json-rest-w... -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Randall Hauch commented on DNA-309: ----------------------------------- Brian sent this link about XSRD, which is an interesting post showing how services can be declared with URI templates: http://www.25hoursaday.com/weblog/2008/10/24/RESTAPIDesignInventMediaType... -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Brian Carothers commented on DNA-309: ------------------------------------- Need to add documentation page to the Wiki describing a typical "session" or expected sequence of interactions. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

[ https://jira.jboss.org/jira/browse/DNA-309?page=com.atlassian.jira.plugin... ] Brian Carothers resolved DNA-309. --------------------------------- Fix Version/s: 0.5 (was: 0.6) Resolution: Done Assignee: Brian Carothers Resolved with the DNA-312 patch. Any future changes to the URI structure should be opened as separate issues. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira