Re: Link Relations

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
>
>
> 
>