RESTful URI Structure RFC

[bcarothers]

https://jira.jboss.org/jira/browse/DNA-55 indicates a desire to add a RESTful interface to DNA. I propose the following URI structure, but I would really appreciate any/all feedback.

URIs for REST Interface

/resources - returns a list of accessible repositories - GET
/resources/repositories - returns a list of accessible repositories - GET
/resources/<repository> - returns a list of accessible workspaces within that repository - GET
/resources/<repository>/workspaces - returns a list of accessible workspaces within that repository - GET
/resources/<repository>/<workspace> - returns a list of operations within the workspace - GET
/resources/<repository>/<workspace>/item/<path> - accesses the node at the path - ALL
/resources/<repository>/<workspace>/item/<path>/@propertyName - accesses the named property at the path - ALL (except PUT)
/resources/<repository>/<workspace>/item/<path>/@propertyName - adds the value from the body to the named property at the path - PUT
/resources/<repository>/<workspace>/uuid/<uuid> - accesses the node with the given UUID - ALL
/resources/<repository>/<workspace>/lock/<path> - locks the node at the path - GET
/resources/<repository>/<workspace>/lock/<path> - unlocks the node at the path - PUT

Operations Supported by Repository but not REST Interface Yet

move
copy
clone
merge

Operations Not Yet Supported by Repository or REST Interface

restore
checkin
checkout
queries

[rhauch]

I think this is a really good start, and something worth starting with. I wouldn't worry too much about the operations not supported by the REST interface, because I think the "item|uuid|lock" level allows use a ton of flexibility within the URL hierarchy (e.g., could use "search" at this level).

[bcarothers]

Looking at this again, I think that /resources should not duplicate the payload of /resources/repositories. I think that this should be:

/resources - Returns some kind of metadata (XSRD?) that describes the URI structure/available
operations for the DNA repository - GET

[rhauch]

Good point. XSRD?

[bcarothers]

I'm not sure if getting the context root should return an XSD file or some kind of JSON object for the server as a whole (a la Sun's cloud API). I'm leaning towards the former, even though I doubt that anyone would really use XSRD for a non-standard interface like this.

Maybe the XSRD piece can be empty for now and figured out later.

[rhauch]

The RESTful world is JSON-oriented. What would the advantages of an XSRD be over a JSON format (especially if this interface wouldn't follow those that normally use XSRD)?

[bcarothers]

I'm all for JSON, but I don't see how to integrate it cleanly with Atom. This could be cluelessness on my part. My current understanding is that DNA would support two "tracks" of RESTful responses (both using the same URI scheme to access resources).

Track 1: AtomPub/XML + XSRD
Track 2: JSON (a la the Sun Cloud API)

If anyone sees a way to unify the two tracks and eliminate work (besides things like using RESTEasy to translate to/from Atom or JSON), please let me know.

[rhauch]

I don't know if I see a way to unify the different approaches. We should pick one and go with it, and add the other as needed. Clients should specify the type of representation they want (via mime type in the HTTP header), so we should eventually be able to support more than one approach. HTML would be a third example.

I'm having difficulty with AtomPub because they lack support for hierarchies. It may make perfect sense for accessing things like named queries that return a single, flattened set of nodes, which could then be turned into AtomPub/XML very easily. But using AtomPub/XML to access any subgraph with depth > 1 seems difficult or requires a hack.