Re: Link Relations

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?

Cheers,
Charles


On Wed, Nov 6, 2013 at 7:09 AM, mike amundsen <[email protected]> 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 <[email protected]>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
>>
>>
>> 
>>
>
>