2 Replies Latest reply on Oct 16, 2012 4:09 AM by marianoguerra

    REST API not so REST?

    marianoguerra

      first of all a disclaimer, IANRF (I'm not Roy Fielding), so this is just my take on REST APIs

       

      looking at the REST documentation,

       

      here: http://docs.jboss.org/hornetq/2.3.0.beta1/docs/rest-manual/html/ch05.html#d0e277

       

      it says: "msg-create: http://example.com/queues/jms.queue.bar/create"

      msg-create

      This is a URL you POST messages to.

       

      I don't know if the last /create is required by the API to specify that it's creating a message or is part of the message name

       

      in case it's part of the API, then POST already means create, so it's not needed.

       

      then it says:

       

      msg-create-with-id

      This is a URL template you POST message to. The semantics of this link are described in Chapter 4.

      in this case, it's better to use the same path for the resource and use PUT, that specifies that a new resource is created and the path (id) is specified by the client

       

      from http://tools.ietf.org/html/draft-pbryan-http-json-resource-03#section-5.1:

       

      The "create" operation allows a client to create a new resource in a

         collection.  A resource is created in one of two ways: if the client

         is requesting a specific identifier, then the resource is created via

         the HTTP PUT method; if the server is to select its own identifier,

         then the resource is created via the POST method.  The PUT method

         SHOULD be preferred over POST.

       

      more information on that RFC draft is useful to have a nice standar REST API

       

      correct me if something makes no sense, I've been exposed to hornetq for some hours

        • 1. Re: REST API not so REST?
          jbertram

          The document from which you quote is a draft for "A Convention for HTTP Access to JSON Resources" which, according to appendix A, does not itself describe a RESTful interface.  I'm not sure the draft is, in fact, "useful to have a nice standar REST API."

           

          As far as I can tell, the HornetQ REST interface adheres to the common REST conventions.  It's also worth noting that there isn't a REST specification per se so how RESTful an interface is can be subject to debate.  That said, based on what you've presented I can't find a reason to implement any changes.

          • 2. Re: REST API not so REST?
            marianoguerra

            my only observation is the use of /create as some kind of RPC method call when POST and PUT already mean create

             

            you can see it in the HTTP method definition http://www.w3.org/Protocols/rfc2616/rfc2616-sec9

             

            The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line.

             

            my interpretation of "as a new subordinate of the resource identified by the Request-URI" is that it lets the server decide the id for ir and return it in some way (maybe a link header)

             

            The PUT method requests that the enclosed entity be stored under the supplied Request-URI

             

            in this case the user provides the resource URI where the resource can later be found (in this case provides de id)

             

            that means that when you create a resource and supply the id for it it should be

             

            PUT http://example.com/queues/jms.queue.bar/002

             

            instead of

             

            POST http://example.com/queues/jms.queue.bar/create/002

             

            and creating it without the id should be

             

            POST http://example.com/queues/jms.queue.bar

             

            instead of

             

            POST http://example.com/queues/jms.queue.bar/create

             

            just that, I wasn't implying all the API is not REST, just that the create method/URI may be improved.