7 Replies Latest reply on May 11, 2009 4:28 PM by Randall Hauch

    RESTful URI Structure RFC

    Brian Carothers Apprentice

      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

        • 1. Re: RESTful URI Structure RFC
          Randall Hauch Master

          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).

          • 2. Re: RESTful URI Structure RFC
            Brian Carothers Apprentice

            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
            



            • 4. Re: RESTful URI Structure RFC
              Brian Carothers Apprentice

              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.

              • 5. Re: RESTful URI Structure RFC
                Randall Hauch Master

                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)?

                • 6. Re: RESTful URI Structure RFC
                  Brian Carothers Apprentice

                  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.

                  • 7. Re: RESTful URI Structure RFC
                    Randall Hauch Master

                    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.