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

19557Re: [rest-discuss] Link Relations

Expand Messages
  • Jan Algermissen
    Nov 10, 2013
    • 0 Attachment
      On 08.11.2013, at 00:10, Charles Reese <charles.reese@...> wrote:

      >
      > Hi Mike,
      >
      > Thank you so much!
      >
      > I'm still wondering about link rels for state-transitions affecting only one resource. For example, suppose when creating a playlist, it defaults to 'private'. I want to turn it public. I could use a link rel like this:
      >
      > /rel/playlist/publish
      >
      > But again, I'm not using the method as the "verb". How would you handle this?

      Make the state a resource and modify that:

      PUT /playlist/77626/state
      Content-Type: application/vnd.foo.state

      <state>live</state>

      Personally, I aim for avoiding the need to introduce a media type for this and use a flag and the creational semantics of PUT:

      PUT /playlist/77626/flags/isLiveFlag
      Content-Length: 0

      201 Created
      ....

      Note that you even get create-if-not-exists semantisc when using If-None-Match: *

      Dig deeper here: http://www.xent.com/pipermail/fork/2001-September/004712.html

      Jan







      >
      > Cheers,
      > Charles
      >
      >
      > On Wed, Nov 6, 2013 at 7:09 AM, mike amundsen <mamund@...> wrote:
      > Charles:
      >
      > First, if you use single strings ("edit", etc.) be sure they are registered Link Relation Values. Here's a good list of references:
      > - IANA [1]
      > - microformats [2]
      > - Dublin Core [3]
      >
      > When you *do* use them, be sure to mention in your documentation which are used and where they are registered.
      >
      > Next, for the cases where you can't find Link Rel Values that suit your needs, use the 5988[4] rules for creating full URIs (not relative) and make them URLs (resolvable) that point to your own documentation/glossary of Link Rel Values online.
      >
      > Finally, when minting your own Link Rel Values, aim for describing the relation between the two resources instead of the action to commit on the "target" resource. Use protocol methods to express the "action" to commit:
      >
      > insert-song -> song (w/ HTTP.POST)
      > remove-song -> song (w/ HTTP.DELETE)
      >
      > Cheers.
      >
      > [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
      > [2] http://microformats.org/wiki/existing-rel-values
      > [3] http://dublincore.org/documents/dcmi-terms/
      > [4] http://tools.ietf.org/html/rfc5988
      >
      >
      >
      > mamund
      > +1.859.757.1449
      > skype: mca.amundsen
      > http://amundsen.com/blog/
      > http://twitter.com/mamund
      > https://github.com/mamund
      > http://www.linkedin.com/in/mamund
      >
      >
      > On Tue, Nov 5, 2013 at 9:52 PM, Charles Reese <charles.reese@...> wrote:
      >
      >
      > Hi all,
      >
      > I'm looking at HAL and Collection+JSON for an API I'm building. I was wondering if there are any community norms for constructing link relations.
      >
      > Here is what I'm considering:
      >
      > Option 1:
      >
      > /rels/playlists
      > /rels/playlist
      > /rels/playlist/insert-song
      > /rels/playlist/remove-song
      >
      > Option 2:
      >
      > /rels/playlist
      > /rels/playlist/create
      > /rels/playlist/edit
      > /rels/playlist/delete
      > /rels/playlist/insert-song
      > /rels/playlist/remove-song
      >
      > Option 3:
      >
      > list
      > create
      > edit
      > delete
      > insert-song
      > remove-song
      >
      > The first option mixes the singular and plural for items and collections. Then it tacks on a few actions for what doesn't fit well with CRUD. The last option makes the state transitions explicit (but doesn't allow linking for docs). The middle option is somewhat in between.
      >
      > Which of these is preferred? Are there better options?
      >
      > Charles
      >
      >
      >
      >
      >
      >
    • Show all 25 messages in this topic