Re: Link Relations

Hi Mike,

On 08.11.2013, at 02:08, mike amundsen <[email protected]> wrote:

> 
> not sure i understand the Q, but i'll offer this:
> 
> rel="http://example.com/rels/publisher" describes the relationship between the source and the target.
> 

I like to try to emphasize what the target is *to the source* with the goal that the application-level effect of the HTTP methods falls into place.

This IMO helps a great deal with avoiding to layer specialized application protocols on top of HTTP (which already is the application protocol).

IOW, it helps prevent redefinitions of the meaning of HTTP methods.  POST means POST, it cannot mean 'publish the source resource'. DELETE means DELETE, it cannot mean 'unpublish the the source resource'.

If you find yourself in a situation that you absolutely must tell the client developer this, rephrase the hypermedia semantic (here: the link rel spec).

There is nothing to say againts hints regarding the intended 'canonical' use case but I can always only be a hint. AtomPub is an example, where the spec tells us so much about the interactions between client and server that it looks like a protocol when it is actually only hints about a canonical application flow. Focussing on resource semantics would have been much nicer, IMHO.

One simply cannot constrain HTTP servers that way and still have REST.

(No to imply, BTW, that Mike did any such thing with his reply - I just felt like adding this before going to sleep :-)

Jan



> now you can describe (or write docs in human form, etc.) how to exploit the relationship using protocols:
> HTTP.POST === publish the source resource
> HTTP.DELETE === unpublish the the source resource
> HTTP.GET === get publishing metadata/status about the source resource
> or whatever (i made up actions since i don't know your domain model)
> 
> hope this helps.
> 
> 
> 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 Thu, Nov 7, 2013 at 6:10 PM, Charles Reese <[email protected]> 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?
> 
> 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
> 
> 
> 
> 
> 
> 
> 



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

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:
    [email protected] 
    [email protected]

<*> To unsubscribe from this group, send an email to:
    [email protected]

<*> Your use of Yahoo Groups is subject to:
    http://info.yahoo.com/legal/us/yahoo/utos/terms/