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

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

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>
Archived-At: <https://mailarchive.ietf.org/arch/msg/art/aJPqntF1byJiQK0lSW-epZDwxQ0>
Subject: Re: [art] "Home" documents for HTTP APIs
Precedence: list

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/

[art] "Home" documents for HTTP APIs Mark Nottingham
Re: [art] "Home" documents for HTTP APIs Carsten Bormann
Re: [art] "Home" documents for HTTP APIs Mark Nottingham