Re: [apps-discuss] json-home: comments and questions on draft 02

Mark Nottingham <mnot@mnot.net> Thu, 15 November 2012 00:37 UTC

Return-Path: <mnot@mnot.net>
X-Original-To: apps-discuss@ietfa.amsl.com
Delivered-To: apps-discuss@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id A333721F8772 for <apps-discuss@ietfa.amsl.com>; Wed, 14 Nov 2012 16:37:32 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -105.071
X-Spam-Level:
X-Spam-Status: No, score=-105.071 tagged_above=-999 required=5 tests=[AWL=-2.472, BAYES_00=-2.599, USER_IN_WHITELIST=-100]
Received: from mail.ietf.org ([64.170.98.30]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id wxAzUYKjo1Oo for <apps-discuss@ietfa.amsl.com>; Wed, 14 Nov 2012 16:37:30 -0800 (PST)
Received: from mxout-08.mxes.net (mxout-08.mxes.net [216.86.168.183]) by ietfa.amsl.com (Postfix) with ESMTP id 2826D21F86E4 for <apps-discuss@ietf.org>; Wed, 14 Nov 2012 16:37:30 -0800 (PST)
Received: from [192.168.1.64] (unknown [118.209.81.233]) (using TLSv1 with cipher AES128-SHA (128/128 bits)) (No client certificate requested) by smtp.mxes.net (Postfix) with ESMTPSA id 5861F509B5; Wed, 14 Nov 2012 19:37:28 -0500 (EST)
Content-Type: text/plain; charset="iso-8859-1"
Mime-Version: 1.0 (Mac OS X Mail 6.2 \(1499\))
From: Mark Nottingham <mnot@mnot.net>
In-Reply-To: <50A38259.4050304@googlemail.com>
Date: Thu, 15 Nov 2012 11:37:29 +1100
Content-Transfer-Encoding: quoted-printable
Message-Id: <3B530232-381D-4370-980B-B5B308443DDF@mnot.net>
References: <50A38259.4050304@googlemail.com>
To: Dirk F5R <dirk.f5r@googlemail.com>
X-Mailer: Apple Mail (2.1499)
Cc: apps-discuss@ietf.org
Subject: Re: [apps-discuss] json-home: comments and questions on draft 02
X-BeenThere: apps-discuss@ietf.org
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: General discussion of application-layer protocols <apps-discuss.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/apps-discuss>, <mailto:apps-discuss-request@ietf.org?subject=unsubscribe>
List-Archive: <http://www.ietf.org/mail-archive/web/apps-discuss>
List-Post: <mailto:apps-discuss@ietf.org>
List-Help: <mailto:apps-discuss-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/apps-discuss>, <mailto:apps-discuss-request@ietf.org?subject=subscribe>
X-List-Received-Date: Thu, 15 Nov 2012 00:37:32 -0000

On 14/11/2012, at 10:36 PM, Dirk F5R <dirk.f5r@googlemail.com> wrote:

> Hi all, hi Mark,
> 
> I had a closer look at http://pretty-rfc.herokuapp.com/draft-nottingham-json-home and http://tools.ietf.org/html/draft-nottingham-json-home-02 since I also absolutely see the need for an API "home page" as well. As a matter of fact, the specs I have contributed to at work come with what we call a "service document" (I can't help using that term in the remainder of this mail). This is only another term for basically the same concept: one single entry point into a hypermedia API that reveals links to something like top-level resources. The URI to the service document is the only thing that needs to be published to client developers, from there we strictly follow the HATEOAS principle.
> 
> I have a few comments / questions on json-home:
> 
> When I look at the json-home draft, it looks to me as if it were actually two separate ones. One that deals with the need of a service document and how it might look like and one that defines how links should look like in JSON. The latter one though is nothing specific to the service document but would rather be a general convention. Shouldn't this be two separate draft documents?

Possibly. The thing is, I'm not yet convinced that there's a single style of linking that's right for all uses -- or even a majority of cases -- in JSON, so I haven't tackled this yet. Having a home document seemed to be the low-hanging fruit, and I expect that if we do one day have a predominant way of linking in JSON, we'll converge on that somehow.

I have talked to Mike about HAL; it may be a contender for enough use cases to be interesting, but I didn't want to tie the fate of this spec to HAL.

In the meantime, the links in json-home are interoperable with other serialisations of links (including HAL). The important thing is that the underlying semantics of the link are well-defined, as per RFC5988. The syntax doesn't matter as much (caveat: see below).


> As to my current perception, I'm also not sure why the service document should have a different format or structure than any other document that comes back from an API. For instance, if your representations always come with an attribute called "links" that hosts explicit links by relation types, why should this be different for the service document? This leads me to the opinion that it should be defined <somewhere> as a requirement that hypermedia APIs must come with a service document but I don't necessarily see the need to define a particular format or media type for it.


Well, we get concrete benefits when off-the-shelf software can consume a known format; having to relearn every format as you encounter it is expensive (in money, time and effort) and error-prone.

My observation is that coming up with a framework that abstracts out the world into a single format convention is Hard (see: RDF), so I decided to try something more modest here. People intuitively understand "home document."

Cheers,

--
Mark Nottingham   http://www.mnot.net/