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

19558Re: [rest-discuss] Link Relations

Expand Messages
  • Jan Algermissen
    Nov 10, 2013
      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?

      And another option is to 'move' the resource into the right collection. E.g. by putting an entry in an AtomPub collection that represents the live-playlists.

      If you think of this as a queue, you are actually creating a better API, because 'publishing' is never a matter of the client actually doing it. Rather, the client 'marks' it for publishing - so the server can do it, when it has the time and resources to do so. Hence: queue semantics.

      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