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

Erik Wilde <> Mon, 08 April 2013 15:55 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 297FD21F903B for <>; Mon, 8 Apr 2013 08:55:23 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -5.67
X-Spam-Status: No, score=-5.67 tagged_above=-999 required=5 tests=[AWL=-0.929, BAYES_20=-0.74, RCVD_IN_DNSWL_MED=-4]
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id JWIJKQILqQSM for <>; Mon, 8 Apr 2013 08:55:22 -0700 (PDT)
Received: from cm04fe.IST.Berkeley.EDU (cm04fe.IST.Berkeley.EDU []) by (Postfix) with ESMTP id 74FF421F975F for <>; Mon, 8 Apr 2013 08:55:20 -0700 (PDT)
Received: from ([] helo=[]) by with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.76) (auth (envelope-from <>) id 1UPEPa-0005Kk-Ej; Mon, 08 Apr 2013 08:55:20 -0700
Message-ID: <>
Date: Mon, 08 Apr 2013 08:55:14 -0700
From: Erik Wilde <>
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:17.0) Gecko/20130328 Thunderbird/17.0.5
MIME-Version: 1.0
To: Jan Algermissen <>
References: <>
In-Reply-To: <>
Content-Type: text/plain; charset="UTF-8"; format="flowed"
Content-Transfer-Encoding: 7bit
Cc: Mark Nottingham <>, "" <>
Subject: Re: [apps-discuss] JSON-Home widget example
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: General discussion of application-layer protocols <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Mon, 08 Apr 2013 15:55:23 -0000

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
>    "" : { "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,