Re: [art] "Home" documents for HTTP APIs

Mark Nottingham <mnot@mnot.net> Sun, 26 March 2017 18:18 UTC

Return-Path: <mnot@mnot.net>
X-Original-To: art@ietfa.amsl.com
Delivered-To: art@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 9A4991270B4 for <art@ietfa.amsl.com>; Sun, 26 Mar 2017 11:18:48 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.602
X-Spam-Level:
X-Spam-Status: No, score=-2.602 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id QEyOR4s45uPd for <art@ietfa.amsl.com>; Sun, 26 Mar 2017 11:18:45 -0700 (PDT)
Received: from mxout-08.mxes.net (mxout-08.mxes.net [216.86.168.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 64475126579 for <apps-discuss@ietf.org>; Sun, 26 Mar 2017 11:18:45 -0700 (PDT)
Received: from dhcp-8ee2.meeting.ietf.org (unknown [31.133.142.226]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.mxes.net (Postfix) with ESMTPSA id 40BD2509B8; Sun, 26 Mar 2017 14:18:43 -0400 (EDT)
Content-Type: text/plain; charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 10.2 \(3259\))
From: Mark Nottingham <mnot@mnot.net>
In-Reply-To: <20170324110136.GC6356@biggiebuntu>
Date: Sun, 26 Mar 2017 13:18:43 -0500
Cc: IETF Apps Discuss <apps-discuss@ietf.org>
Content-Transfer-Encoding: quoted-printable
Message-Id: <1CBCB1EF-983B-4470-8BD6-437193C86175@mnot.net>
References: <5CB15D9F-D50F-4A78-8AC0-21B835534D23@mnot.net> <20170324110136.GC6356@biggiebuntu>
To: Stian Soiland-Reyes <soiland-reyes@manchester.ac.uk>
X-Mailer: Apple Mail (2.3259)
Archived-At: <https://mailarchive.ietf.org/arch/msg/art/aJPqntF1byJiQK0lSW-epZDwxQ0>
X-Mailman-Approved-At: Fri, 07 Apr 2017 04:57:48 -0700
Subject: Re: [art] "Home" documents for HTTP APIs
X-BeenThere: art@ietf.org
X-Mailman-Version: 2.1.22
Precedence: list
List-Id: Applications and Real-Time Area Discussion <art.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/art>, <mailto:art-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/art/>
List-Post: <mailto:art@ietf.org>
List-Help: <mailto:art-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/art>, <mailto:art-request@ietf.org?subject=subscribe>
X-List-Received-Date: Sun, 26 Mar 2017 18:18:48 -0000

Hi,

As mentioned in the appendix, the focus here is different; it's targeting APIs that have multiple deployments and multiple consumer implementations, all uncoordinated -- i.e., the sort of thing that we generally create in standards. 

Cheers,



> On 24 Mar 2017, at 6:01 am, Stian Soiland-Reyes <soiland-reyes@manchester.ac.uk>; wrote:
> 
> On Wed, 15 Mar 2017 16:17:07 +1100, Mark Nottingham <mnot@mnot.net>; wrote:
>> Hi art[-discuss],
>> 
>> I've had a document on the back burner for a while about a "home document" for non-brower uses of HTTP.
>> 
>>  https://datatracker.ietf.org/doc/draft-nottingham-json-home/
>>  https://mnot.github.io/I-D/json-home/
>> 
>> The idea is to promote good practice, especially regarding allowing the server to control its own URLs (as per RFC7320) -- especially in the case where there are likely to be multiple implementations, multiple servers and multiple clients deployed (i.e., standards).
>> 
>> This differentiates it from other "HTTP API description formats" that you might have come across. See the Introduction for a more full explanation.
>> 
>> It's come to a point where there's a non-trival (but not huge) community of folks interested in it and implementing it; e.g., see: 
>>  https://github.com/mnot/I-D/wiki/json-home
>>  https://github.com/mnot/I-D/issues?utf8=✓&q=label%3Ajson-home%20
>> 
>> However, I'm not sure about next steps. What I'd like to hear from folks here is whether people think defining this would help IETF protocols that use HTTP (of which there seem to be more every day).
>> 
>> Any thoughts?
> 
> Is there a good reason why say a Swagger/Open API specification document
> is not appropriate as the "JSON Home" document? It seems that as you
> start defining URI templates and so on, you are stepping into that
> territory.
> 
> https://www.openapis.org/
> 
> 
> What I think Open API does not have is a way to identify the (type) of
> service/endpoint by URI, as your tag: examples.
> 
> 
> -- 
> Stian Soiland-Reyes
> The University of Manchester
> http://www.esciencelab.org.uk/
> http://orcid.org/0000-0001-9842-9718
> 

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