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

Re: [rest-discuss] Link relation for adding a resource

Expand Messages
  • Paul Cohen
    Hi, Thanks for the feedback. Mike, I ve registered myself to the link-relations list. However I d like to continue the discussion here first. ... I have
    Message 1 of 11 , Sep 1, 2012
    • 0 Attachment
      Hi,

      Thanks for the feedback.

      Mike, I've registered myself to the link-relations list. However I'd
      like to continue the discussion here first.

      On Fri, Aug 31, 2012 at 6:55 PM, mike amundsen <mamund@...> wrote:
      > I think registering a link relation w/ the IANA that conveys the meaning of
      > "use this URL to create a new resource of the type you are currently
      > viewing" would be valuable. I'd would prefer the value "create" over "add"
      > or "new" as I think it a broader value that covers not just adding new items
      > to a collection, but also creating new stand-alone content, etc.

      I have previously designed and implemented a few "read-only" HTTP
      API:s (as REST-ful as possible!) and I have only had the need for
      using the methods GET HEAD and OPTIONS. This has made the linking
      aspect of the API rather straight forward for me. I have been able to
      use established link relation types without any significant problems.

      However, now I'm designing a more interactive HTTP API for a
      company-internal production system and I have the need for
      creating/adding new resources. I now find that for more interactive
      HTTP API:s there seems to be a lack of established link relation
      types.

      To elaborate a bit on you suggestion Mike, and based on my current
      needs, I would like to propose:

      1. "create": "Use this URL to create a new resource (possibly without
      providing any data)".

      2. "add": "Use this URL to add an existing resource by providing data".

      3. "remove": "Use this URL to remove an existing resource".

      4. "start": "Use this URL to start an 'execution' resource". Eg:
      transaction, update, dump, backup etc. These resources are typically
      transient. In my case I have an resource representing a ongoing
      download of various data sets.

      5. "stop": Use this URL to stop an execution resource".

      /Paul

      --
      Paul Cohen
      www.seibostudios.se
      mobile: +46 730 787 035
      e-mail: paul.cohen@...
    • Jan Algermissen
      ... HTTP POST has that semantic already, there is no need to use a link relation for that. All you need to know is that some resource has collection semantics,
      Message 2 of 11 , Sep 1, 2012
      • 0 Attachment
        On Aug 31, 2012, at 6:07 PM, Paul Cohen wrote:

        > Hi,
        >
        > I would like to define, in JSON, a link that provides a way to add a
        > new resource to a collection of resources.

        HTTP POST has that semantic already, there is no need to use a link relation for that.

        All you need to know is that some resource has collection semantics, so you should tell the client that /photos is a collection rather than focussing on the action.


        E.g. tell the client that /photos/ is the 'photos collection' (you can use a link rel for that, or, e.g. an AtomPub service document, or a specific media type you design) and that's it. That POST is for adding items is known from HTTP already.

        Jan


        > I'm considering this:
        >
        > "link": {
        > "href": "/photos/",
        > "type": "image/tiff",
        > "method": "POST",
        > "rel": "new",
        > "title": "Add new photo"}
        >
        > I'd appreciate any comments on the link representation above. In
        > particular I'm interested in suggestions for the relation type - I use
        > "new" above. I've seen "new" being used in similar cases but it's not
        > an officially registered relation type here:
        >
        > * http://www.iana.org/assignments/link-relations/link-relations.xml
        >
        > * http://www.w3.org/TR/html401/types.html#h-6.12
        >
        > * http://microformats.org/wiki/existing-rel-values
        >
        > And there's no registered relation type with new/add/append-like
        > semantics. Well maybe "create-form" on the mircroformats page, but
        > that doesn't really seem appropriate.
        >
        > /Paul
        >
        > --
        > Paul Cohen
        > www.seibostudios.se
        > mobile: +46 730 787 035
        > e-mail: paul.cohen@...
        >
      • mike amundsen
        There are multiple ways to communicate interaction semantics of a problem domain within a response: 1 - mapping via link decorator such as @rel, @id, @name,
        Message 3 of 11 , Sep 1, 2012
        • 0 Attachment
          There are multiple ways to communicate interaction semantics of a problem domain within a response:
          1 - mapping via link decorator such as @rel, @id, @name, etc. (i.e. rel="create" === add)
          2 - mapping via document element (i.e. <create href="..." ... /> === add)
          3 - mapping via protocol method (i.e. POST === add)
          4 - mapping via resource identifier or identifier segment  (i.e. /..../?create === add)

          The first two possibilities offer the most flexibility and evolvability over time since the client binds problem domain specifics to the response details (deocrator/element) which may appear in any response sent over any protocol using any identifier.

          The second two possibilities offer the least flexibility and evolvability over time since these solutions lead clients to bind problem domain specifics to protocol-level details that are usually harder to change over time and provide less portability (i.e. new protocols or identifier schemes, etc.).


          mca
          http://amundsen.com/blog/
          http://twitter.com@mamund
          http://mamund.com/foaf.rdf#me




          On Sat, Sep 1, 2012 at 8:44 AM, Jan Algermissen <jan.algermissen@...> wrote:

          On Aug 31, 2012, at 6:07 PM, Paul Cohen wrote:

          > Hi,
          >
          > I would like to define, in JSON, a link that provides a way to add a
          > new resource to a collection of resources.

          HTTP POST has that semantic already, there is no need to use a link relation for that.

          All you need to know is that some resource has collection semantics, so you should tell the client that /photos is a collection rather than focussing on the action.


          E.g. tell the client that /photos/ is the 'photos collection' (you can use a link rel for that, or, e.g. an AtomPub service document, or a specific media type you design) and that's it. That POST is for adding items is known from HTTP already.

          Jan


          > I'm considering this:
          >
          > "link": {
          > "href": "/photos/",
          > "type": "image/tiff",
          > "method": "POST",
          > "rel": "new",
          > "title": "Add new photo"}
          >
          > I'd appreciate any comments on the link representation above. In
          > particular I'm interested in suggestions for the relation type - I use
          > "new" above. I've seen "new" being used in similar cases but it's not
          > an officially registered relation type here:
          >
          > * http://www.iana.org/assignments/link-relations/link-relations.xml
          >
          > * http://www.w3.org/TR/html401/types.html#h-6.12
          >
          > * http://microformats.org/wiki/existing-rel-values
          >
          > And there's no registered relation type with new/add/append-like
          > semantics. Well maybe "create-form" on the mircroformats page, but
          > that doesn't really seem appropriate.
          >
          > /Paul
          >
          > --
          > Paul Cohen
          > www.seibostudios.se
          > mobile: +46 730 787 035
          > e-mail: paul.cohen@...
          >



          ------------------------------------

          Yahoo! Groups Links

          <*> To visit your group on the web, go to:
              http://groups.yahoo.com/group/rest-discuss/

          <*> Your email settings:
              Individual Email | Traditional

          <*> To change settings online go to:
              http://groups.yahoo.com/group/rest-discuss/join
              (Yahoo! ID required)

          <*> To change settings via email:
              rest-discuss-digest@yahoogroups.com
              rest-discuss-fullfeatured@yahoogroups.com

          <*> To unsubscribe from this group, send an email to:
              rest-discuss-unsubscribe@yahoogroups.com

          <*> Your use of Yahoo! Groups is subject to:
              http://docs.yahoo.com/info/terms/


        • Erik Wilde
          hello jan. ... why do you think POST has create semantics? POST does not have any semantics other than doing something non-safe non-idempotent. while create
          Message 4 of 11 , Sep 1, 2012
          • 0 Attachment
            hello jan.

            On 2012-09-01 05:44 , Jan Algermissen wrote:
            > On Aug 31, 2012, at 6:07 PM, Paul Cohen wrote:
            >> I would like to define, in JSON, a link that provides a way to add a
            >> new resource to a collection of resources.
            > HTTP POST has that semantic already, there is no need to use a link relation for that.

            why do you think POST has create semantics? POST does not have any
            semantics other than doing something non-safe non-idempotent. while
            create fits that pattern, it's much more specific and not something that
            is in any way defined by HTTP itself.

            > All you need to know is that some resource has collection semantics, so you should tell the client that /photos is a collection rather than focussing on the action.

            you're assuming that by exposing collection semantics this inherently
            means you can POST to create. again, that's not something that HTTP
            tells you. for example, AtomPub says that in order to create, you have
            to POST to an "edit" link, and not just to the collection itself. you
            could define a media type where the rule would be that you can always
            POST to a collection's URI to create a new resource, but that would be
            semantics defined by that media type, and not by HTTP itself.

            cheers,

            dret.

            --
            erik wilde | mailto:dret@... - tel:+1-510-2061079 |
            | UC Berkeley - School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |
          • Roy T. Fielding
            ... The original definition of POST was the same as NNTP: post an article to a group (where group is the container identified by the target URI). Hence, create
            Message 5 of 11 , Sep 1, 2012
            • 0 Attachment
              On Sep 1, 2012, at 11:00 AM, Erik Wilde wrote:
              > On 2012-09-01 05:44 , Jan Algermissen wrote:
              >> On Aug 31, 2012, at 6:07 PM, Paul Cohen wrote:
              >>> I would like to define, in JSON, a link that provides a way to add a
              >>> new resource to a collection of resources.
              >> HTTP POST has that semantic already, there is no need to use a link relation for that.
              >
              > why do you think POST has create semantics? POST does not have any
              > semantics other than doing something non-safe non-idempotent.

              The original definition of POST was the same as NNTP: post an article
              to a group (where group is the container identified by the target URI).
              Hence, create a new resource under the target and respond with its
              new URI in Location.

              POST has strayed quite a bit since then.

              ....Roy
            • Jan Algermissen
              ... I am interpreting POST along the lines Roy referred to ( append ) since that has arguably been blurred, my thinking seems wrong in that sense. Anyhow,
              Message 6 of 11 , Sep 2, 2012
              • 0 Attachment
                On Sep 1, 2012, at 8:00 PM, Erik Wilde wrote:

                > hello jan.
                >
                > On 2012-09-01 05:44 , Jan Algermissen wrote:
                > > On Aug 31, 2012, at 6:07 PM, Paul Cohen wrote:
                > >> I would like to define, in JSON, a link that provides a way to add a
                > >> new resource to a collection of resources.
                > > HTTP POST has that semantic already, there is no need to use a link relation for that.
                >
                > why do you think POST has create semantics?

                I am interpreting POST along the lines Roy referred to ( "append" ) since that has arguably been blurred, my thinking seems 'wrong' in that sense.

                Anyhow, you do not need to specify alink relation for adding items. it is sufficient to say that collections have that semantic. The use of POST follows naturally, because what else would you use? A client is free to try a PUT and will find out at run time whether that works.


                > POST does not have any
                > semantics other than doing something non-safe non-idempotent. while
                > create fits that pattern, it's much more specific and not something that
                > is in any way defined by HTTP itself.
                >
                > > All you need to know is that some resource has collection semantics, so you should tell the client that /photos is a collection rather than focussing on the action.
                >
                > you're assuming that by exposing collection semantics this inherently
                > means you can POST to create. again, that's not something that HTTP
                > tells you. for example, AtomPub says that in order to create, you have
                > to POST to an "edit" link, and not just to the collection itself.

                Huh? Seems you are mixing editing with creating entries, or?

                That aside, the interaction descriptions the AtomPub spec gives, are an over specification, because the server is free to do what it wants and the client has to be able to deal with that. Constraining the methods to use is a kind of coupling you cannot have (in a REStful system).

                It is interesting that people usually seem to think specification of the method to use is necessary to implement clients and servers, but when you think about it, the choices are so limited that a developers knows the method to use anyhow.

                Hints are good, but hey are just that, hints.

                > you
                > could define a media type where the rule would be that you can always
                > POST to a collection's URI to create a new resource, but that would be
                > semantics defined by that media type, and not by HTTP itself.

                Yes you could, but IMHO it's YAGNI and from a @RESTPOLICE POV, forbidden :-)


                Jan


                >
                > cheers,
                >
                > dret.
                >
                > --
                > erik wilde | mailto:dret@... - tel:+1-510-2061079 |
                > | UC Berkeley - School of Information (ISchool) |
                > | http://dret.net/netdret http://twitter.com/dret |
                >
              • Steve Klabnik
                ... Yep: http://bitworking.org/projects/atom/rfc5023.html#post-to-create
                Message 7 of 11 , Sep 2, 2012
                • 0 Attachment
                  >> tells you. for example, AtomPub says that in order to create, you have
                  >> to POST to an "edit" link, and not just to the collection itself.
                  >
                  > Huh? Seems you are mixing editing with creating entries, or?

                  Yep: http://bitworking.org/projects/atom/rfc5023.html#post-to-create

                  > The client POSTs a representation of the Member to the URI of the Collection.
                • Erik Wilde
                  hello jan. ... i wouldn t call it wrong, just more constrained than it actually is. if it were append only, we wouldn t have anything other than append to
                  Message 8 of 11 , Sep 2, 2012
                  • 0 Attachment
                    hello jan.

                    On 2012-09-02 04:38 , Jan Algermissen wrote:
                    >> why do you think POST has create semantics?
                    > I am interpreting POST along the lines Roy referred to ( "append" ) since that has arguably been blurred, my thinking seems 'wrong' in that sense.

                    i wouldn't call it wrong, just more constrained than it actually is. if
                    it were "append" only, we wouldn't have anything other than "append" to
                    do non-append things with. i am trying to avoid explaining the HTTP
                    methods as equivalents of CRUD operations, it tends to confuse people.

                    > Anyhow, you do not need to specify alink relation for adding items. it is sufficient to say that collections have that semantic. The use of POST follows naturally, because what else would you use? A client is free to try a PUT and will find out at run time whether that works.

                    agreed here, if you say it's a collection, then clients may implicitly
                    try a POST, if that's what collections imply. but.... {see further down)

                    >> you're assuming that by exposing collection semantics this inherently
                    >> means you can POST to create. again, that's not something that HTTP
                    >> tells you. for example, AtomPub says that in order to create, you have
                    >> to POST to an "edit" link, and not just to the collection itself.
                    > Huh? Seems you are mixing editing with creating entries, or?

                    yes i did. my apologies for the confusion!

                    > That aside, the interaction descriptions the AtomPub spec gives, are an over specification, because the server is free to do what it wants and the client has to be able to deal with that. Constraining the methods to use is a kind of coupling you cannot have (in a REStful system).
                    > It is interesting that people usually seem to think specification of the method to use is necessary to implement clients and servers, but when you think about it, the choices are so limited that a developers knows the method to use anyhow.

                    aren't you contradicting yourself a little bit here? it seems to me that
                    above you're saying that a client needs to understand something is a
                    collection (this would be signaled by the media type, right?) that might
                    support POST. so we need this level of shared understanding, and i agree
                    that one possible design is to not have an explicit link and instead say
                    that "a create link is implied to the same URI, so that clients can try
                    POST." but that needs to be specified somewhere, and it needs to be in
                    the media type, right? the media type can use an "implicit link" ("use
                    the same URI and POST to it") or an explicit one ("follow the 'create'
                    link and POST to that URI"), but one way or the other, there is a "typed
                    link" and there is a rule what HTTP method to use when following it.

                    cheers,

                    dret.

                    --
                    erik wilde | mailto:dret@... - tel:+1-510-2061079 |
                    | UC Berkeley - School of Information (ISchool) |
                    | http://dret.net/netdret http://twitter.com/dret |
                  Your message has been successfully submitted and would be delivered to recipients shortly.