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

Re: [rest-discuss] Where should I POST to?

Expand Messages
  • 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 1 of 8 , Mar 1 12:20 AM
    • 0 Attachment
      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 2 of 8 , Mar 1 1:04 AM
      • 0 Attachment
        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 3 of 8 , Mar 1 1:20 AM
        • 0 Attachment
          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 4 of 8 , Mar 1 3:36 AM
          • 0 Attachment
            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 5 of 8 , Mar 1 12:54 PM
            • 0 Attachment
              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 6 of 8 , Mar 2 5:51 AM
              • 0 Attachment
                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 7 of 8 , Mar 6 1:12 AM
                • 0 Attachment
                  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.