Loading ...
Sorry, an error occurred while loading the content.
 

Where should I POST to?

Expand Messages
  • Ruben Verborgh
    Hi everyone, A hypothetical blog application: - /posts/43 identifies a blog post resource - /posts/43/comments/3 identifies a comment resource on this blog
    Message 1 of 8 , Feb 29, 2012
      Hi everyone,

      A hypothetical blog application:
      - /posts/43 identifies a blog post resource
      - /posts/43/comments/3 identifies a comment resource on this blog post

      Here are different ideas to create a comment:
      - POST on /posts/43
      According to the definition of POST [1], this should be acceptable under “annotation of existing resources”.
      - POST on /posts/43/comments
      According to the definition of POST [1], this should be acceptable under “posting a message […]”

      The question: which one(s) of the above seem acceptable, which one is “best”?

      For this, you also have to consider that the resource identified by “/posts/43/comments”—while it clearly exists and is well-defined—is rather meaningless to the application in question, since:
      - People will never GET /posts/43/comments, because the comments will be served along with every representation of the /posts/43 resource
      - PUT and DELETE on /posts/43/comments will also never be of practical use (you can’t update all comments at once nor delete the comments collection).

      So, rephrasing, do I need the /posts/43/comments resource (which will only serve for POST requests) or can I happily POST to /posts/43 in a correct hypermedia API?

      [1] http://tools.ietf.org/html/rfc2616#section-9.5

      --
      Ruben Verborgh
      http://twitter.com/RubenVerborgh
      PhD Student at Multimedia Lab – IBBT / ELIS, Ghent University, Belgium

      Make your hypermedia API ready for intelligent agents via http://restdesc.org/.
    • Philippe Mougin
      ... Both are acceptable. If you expose the collection of comments as a resource, there are benefits to use this resource as a factory for creating individual
      Message 2 of 8 , Mar 1, 2012
        Le 1 mars 2012 à 08:45, Ruben Verborgh <ruben.verborgh@...> a écrit :

        > Hi everyone,
        >
        > A hypothetical blog application:
        > - /posts/43 identifies a blog post resource
        > - /posts/43/comments/3 identifies a comment resource on this blog post
        >
        > Here are different ideas to create a comment:
        > - POST on /posts/43
        > According to the definition of POST [1], this should be acceptable under “annotation of existing resources”.
        > - POST on /posts/43/comments
        > According to the definition of POST [1], this should be acceptable under “posting a message […]”
        >
        > The question: which one(s) of the above seem acceptable, which one is “best”?

        Both are acceptable. If you expose the collection of comments as a resource, there are benefits to use this resource as a factory for creating individual comment resources using POST interactions (i.e., your second idea).

        > For this, you also have to consider that the resource identified by “/posts/43/comments”—while it clearly exists and is well-defined—is rather meaningless to the application in question, since:
        > - People will never GET /posts/43/comments, because the comments will be served along with every representation of the /posts/43 resource
        > - PUT and DELETE on /posts/43/comments will also never be of practical use (you can’t update all comments at once nor delete the comments collection).
        >
        > So, rephrasing, do I need the /posts/43/comments resource (which will only serve for POST requests) or can I happily POST to /posts/43 in a correct hypermedia API?

        You can happily POST to /post/43

        Best,
        Philippe Mougin
      • Mike Kelly
        ... They re both valid. The first option is arguably a slightly better interaction as it s more visible because, as you say, the comments are represented from
        Message 3 of 8 , Mar 1, 2012
          On Thu, Mar 1, 2012 at 7:45 AM, Ruben Verborgh <ruben.verborgh@...> wrote:
          > Hi everyone,
          >
          > A hypothetical blog application:
          > - /posts/43 identifies a blog post resource
          > - /posts/43/comments/3 identifies a comment resource on this blog post
          >
          > Here are different ideas to create a comment:
          > - POST on /posts/43
          >  According to the definition of POST [1], this should be acceptable under “annotation of existing resources”.
          > - POST on /posts/43/comments
          >  According to the definition of POST [1], this should be acceptable under “posting a message […]”
          >
          > The question: which one(s) of the above seem acceptable, which one is “best”?
          >

          They're both valid. The first option is arguably a slightly better
          interaction as it's more visible because, as you say, the comments are
          represented from this resource and so a successful POST would
          automatically invalidate it in any participating caches. That's quite
          useful because it allows you more generous Cache-Control max-age
          values - it's particularly useful for gateway caching, specifically.

          If your clients are driven by hypertext you can pick whichever one you
          want.. if you found that you needed to switch from one to the other -
          changing the URI would not disturb your clients.

          Cheers,
          Mike
        • Ruben Verborgh
          Hi Mike and Philippe, Thanks for helping. I see that both options are acceptable. ... Well, my envisioned clients are indeed driven by hypertext. I’m working
          Message 4 of 8 , Mar 1, 2012
            Hi Mike and Philippe,

            Thanks for helping. I see that both options are acceptable.

            > If your clients are driven by hypertext you can pick whichever one you
            > want.. if you found that you needed to switch from one to the other -
            > changing the URI would not disturb your clients.

            Well, my envisioned clients are indeed driven by hypertext.
            I’m working on describing hypermedia APIs, and currently, collection resources such as ../comments pose a problem:

            It’s easy to describe the relationship between a blog post and an individual comment:
            Link: </posts/43/comment/3>; rel=“http://example.org/blog#comment%e2%80%9d
            Clients just need to understand the http://example.org/blog#comment relation then.

            However, it’s more difficult to link to the comments (plural) resource as well:
            Link: </posts/43/comments>; rel=“http://example.org/blog#comments%e2%80%9d
            because this means that 1) I’d have to maintain all link relationships twice (singular and plural) and 2) hypermedia clients have to understand twice as many relationship types.

            So if I can stick to posting to the /posts/43 resource, that’s a lot easier. Thanks!

            Best,

            Ruben
          • Mike Kelly
            ... The default, sure. It s trivial to overcome though - Rails routing is very flexible.
            Message 5 of 8 , Mar 1, 2012
              On Thu, Mar 1, 2012 at 11:24 AM, Steve Klabnik <steve@...> wrote:
              >> They're both valid. The first option is arguably a slightly better
              >> interaction as it's more visible because, as you say, the comments are
              >> represented from this resource and so a successful POST would
              >> automatically invalidate it in any participating caches. That's quite
              >> useful because it allows you more generous Cache-Control max-age
              >> values - it's particularly useful for gateway caching, specifically.
              >
              > This is a great point. Yet another failing of the default way that
              > Rails does things; you'd be POSTing to /posts/42/comments in that
              > case...

              The default, sure. It's trivial to overcome though - Rails' routing is
              very flexible.
            • Craig McClanahan
              ... * POST /posts/43/comments is a well defined resource (it s a collection of all the comments so far for this post) * It is perfectly reasonable to support
              Message 6 of 8 , Mar 1, 2012
                On Wed, Feb 29, 2012 at 11:45 PM, Ruben Verborgh <ruben.verborgh@...> wrote:
                Hi everyone,

                A hypothetical blog application:
                - /posts/43 identifies a blog post resource
                - /posts/43/comments/3 identifies a comment resource on this blog post

                Here are different ideas to create a comment:
                - POST on /posts/43
                 According to the definition of POST [1], this should be acceptable under “annotation of existing resources”.
                - POST on /posts/43/comments
                 According to the definition of POST [1], this should be acceptable under “posting a message […]”

                The question: which one(s) of the above seem acceptable, which one is “best”?

                I tend to prefer the second approach for scenarios like this:

                * POST /posts/43/comments is a well defined resource (it's a collection of all the comments so far for this post)

                * It is perfectly reasonable to support getting all the comments for a post in a single call (GET /posts/43/comments),
                  perhaps with optional query parameters to control filtering or pagination.

                * If you have other sorts of resources related to your root resource, it's straightforward to name
                  additional collections ("POST /posts/43/attachments" will add an attachment to that post)
                  and I don't have any ambiguity if I want the attachments (GET /posts/43/attachments) or
                  the comments (GET /posts/43/comments).

                In all cases, I'd suggest including the ".../comments" and ".../attachments" links (in whatever format you're using for representations) as resource links in the post representation returned by "GET /posts/43" so that a client doesn't have to know or care which choice you made ... they just follow the provided links.

                Craig

              • Jon Hanna
                ... One could choose to have a GET to /posts/43/comments 301 to /posts/43#comments. Or to just add a GET that returns an entity of just the comments, or simply
                Message 7 of 8 , Mar 2, 2012
                  On 2012-03-01 07:45, Ruben Verborgh wrote:
                  > - People will never GET /posts/43/comments, because the comments will be served along with every representation of the /posts/43 resource

                  One could choose to have a GET to /posts/43/comments 301 to
                  /posts/43#comments. Or to just add a GET that returns an entity of just
                  the comments, or simply say "well, if I made GET do anything it would be
                  to return an entity that shows just the comments, but since it'll never
                  be used I'm not going to bother implementing it".

                  The main reason I'd argue in favour of posting to /posts/43 is that the
                  relationship between /posts/43 and /posts/43 is obvious, while the
                  relationship between it and what is (relative to it) ./43/comments is
                  less so. Had the post had the URI /posts/43/ with a trailing slash, then
                  this would be less so pressing.

                  All of this is about niceties though. /adfs/d32rsdf/1ras89%20sfdakl
                  would be just as good as either from a purely REST perspective, but
                  niceties do matter.
                • Ruben Verborgh
                  Hi Jon, ... Interesting option indeed. ... True. It is easy to make the relationship from the blog post to a comment, and from each comment to the collection
                  Message 8 of 8 , Mar 6, 2012
                    Hi Jon,

                    > One could choose to have a GET to /posts/43/comments 301 to
                    > /posts/43#comments. Or to just add a GET that returns an entity of just
                    > the comments, or simply say "well, if I made GET do anything it would be
                    > to return an entity that shows just the comments, but since it'll never
                    > be used I'm not going to bother implementing it”.

                    Interesting option indeed.

                    > The main reason I'd argue in favour of posting to /posts/43 is that the
                    > relationship between /posts/43 and /posts/43 is obvious, while the
                    > relationship between it and what is (relative to it) ./43/comments is
                    > less so. Had the post had the URI /posts/43/ with a trailing slash, then
                    > this would be less so pressing.

                    True. It is easy to make the relationship from the blog post to a comment, and from each comment to the collection of all comments. But from the blog post to all comments is less convenient, all the more since we would serve all the comments in the post’s representation anyway.

                    > All of this is about niceties though. /adfs/d32rsdf/1ras89%20sfdakl
                    > would be just as good as either from a purely REST perspective, but
                    > niceties do matter.

                    I beg to differ here: the question is not about the exact URI used, but about the resource that is identified by that URI.

                    I my example /posts/43 was the resource “blog post 43” and /posts/43/comments the resource “comments to blog post 43”.
                    Now whether the URI to these resources is /posts/43 and /posts/43/comments or /bar and /foo doesn’t matter; but they *are* different resources.
                    Therefore, my question was to which resource I should POST, i.e., what resource does /adfs/d32rsdf/1ras89%20sfdakl identify?

                    Best,

                    Ruben
                  Your message has been successfully submitted and would be delivered to recipients shortly.