Re: [apps-discuss] JSON-Home widget example

[Erik Wilde <[e-mail]>]

hello jan.

On 2013-04-08 04:11 , Jan Algermissen wrote:
> For example, a bunch of orders can be straight forward exposed as
>    /orders
> and knowing that
>    "http://example.org/rel/orders" : { "href" : "/orders" }
> pretty much implies something like /orders/{orderId}, including the idea that adding an order is likely done with a POST to /orders and that editing an order is (maybe) achieved with PUT/PATCH/DELETE.
> What troubles me is that JSON Home currently makes it necessary to define two link relations to cover a standard (in a sense) use case that could be covered with just one link relation. Or, in other words, the two link rels somehow semantically overlap, yet demand two 'specifications'. Think in terms of violating DRY.

Home Documents really don't "make it necessary" to define the link 
relation for the collection. it's simply what the example is using, and 
of course you are free to do it differently. in the end, it is up to the 
service designer to decide which link relations they use/define, and 
which they want to expose in the home document.

our service currently uses "collection" links to link from instances in 
collections to the collection itself, so coming back to your example, 
the only have "widget" links (which are templated), but we don't (yet) 
have a "widgets" link. we're still debating how to best map this to the 
home document we're exposing, and you could make a point that maybe in a 
very rich semantic world, you might be able to say "widget collection", 
indicating that the link points to "a collection of widget things". but 
that, imho, is not really working very well for arbitrary link 
relations, so we are currently leaning towards introducing "widgets" as 
a link relation, because we want to provide such a link to a collection 
in the home document, and we want to be specific about what that 
collection contains.

to repeat myself, i don't think that home documents themselves have a 
lot to say or do here; they simply give you a format for how to expose 
typed links in one place, and what you're exposing there is entirely 
under your control, and your responsibility. hardcoding the "collection 
pattern" into home documents would immediately cause other patterns to 
become candidates as well, and i don't think home documents are the 
right place to start standardizing a couple of ways in which resources 
in HTTP services may be related.

thanks and cheers,

dret.