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

From: Mark Nottingham <[email-masked]>
Date: Sun, 26 Mar 2017 13:18:43 -0500

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 <[email-masked]> wrote:
> 
> On Wed, 15 Mar 2017 16:17:07 +1100, Mark Nottingham <[email-masked]> 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/