[art] "Home" documents for HTTP APIs

[Mark Nottingham]

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?

Thanks,


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

[Carsten Bormann]

draft-ietf-core-links-json just finished second WGLC in core.
That is clearly solving a different problem (making RFC 6690 available in JSON/CBOR), but I can’t help noticing that there are some commonalities.
RFC 6690, of course, is the “home document” for CoRE.
Also, OCF has /oic/res, which is in the same mold.

No idea whether this semblance should have any impact on either document, but maybe food for thought.

(Yes, I have read Appendix D. Maybe I should point to draft-hartke-t2trg-coral as one take on the “form” gap. Input on this is very welcome over in T2TRG.)

Grüße, Carsten

[resent this because of "Message has implicit destination” breakage.]

_______________________________________________
art mailing lis

[Mark Nottingham]

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,

Post by Mark Nottingham
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.
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/