[dispatch] Re: New work: well-known URI for API change advisories (draft-callec-api-advisory-00)

[[e-mail]]

Regarding my previous comments, I leave it to the authors' judgment what
to do with them, since they will think about them a lot more than I
will.

But then let me raise another suggestion:  The major "value adds" in the
draft are (1) having a well-known URL path attached to the DNS name of
the API service endpoint, and (2) defining the desirable metadata for
the service announcement items.

I was thinking that the Json format cataloging the announcements might
be upgraded in this way:  The well-known URL returns a fairly simple
(but versionized!) JSON structure whose primary data item is the URL of
an Atom syndication server.

The pointed-to Atom server then serves up the service announcements.
This hands over the definition of how to serve up an endless stream of
announcements to the well-debugged RFC 4287, as well as handing over the
implementation of fetching the announcements to existing Atom
implementations.

draft-callec-api-advisory specifies a lot of standardized metadata
fields that are attached to the individual announcements in whatever the
standard way is for providing metadata for blog posts.  The Gemini
answer suggests that the draft can define its own XML namespace for
metadata tags.

Also, I haven't read the draft but you need to think through the case
where the FQDN contains several URLs that are access points for distinct
APIs.  Are those considered largely unconnected (in which case the JSON
needs to list separate announcement support for each one) or largely
connected (in which case the document should state explicitly that the
announcement stream applies to all URLs at that FQDN)?  The proper
answer to this probably depends on actual industrial practice (which I
do not know).

Dale