Last Call Review of draft-ietf-httpapi-api-catalog-05
review-ietf-httpapi-api-catalog-05-artart-lc-bray-2024-10-23-00

The notion of having a /.well-known/api-catalog seems perfectly sensible, and I
see nothing wrong with the description of what it should contain. I have a
bunch of basically editorial nits, most of which are HTTP/URI pedantry.

Section 1. "An organisation or individual may publish Application Programming
Interfaces (APIs)". A little confusing. I think that what you mean is that an
org can publish API specifications to allow people to build software to use its
provided APIs. So maybe "specifications of" in front of the first occurrence? 
Or maybe "In this document, 'API' means the specification resources required
for an external party to implement software which uses the Application
Programming Interface", or some such

Section 1. "a well-known URI, 'api-catalog', as a reference to the URI of". Um,
do you publish the URI, or a URI Reference [RFC3986] or what? I think you just
publish a URI, encoded as a URI reference?

Section 1. "a link relation", should the term "link relation" be supported with
a citation? I think I know what you mean but some won't?

Section 1. "a well-known URI [RFC8615] that returns an API catalog". URIs don't
"return" documents, they "identify" documents.

Section 2. "SHOULD publish the /.well-known/api-catalog URI at a predictable
location." This section is troublesome. RFC 8615, which you cite, begins "This
memo defines a path prefix for "well-known locations",  "/.well-known/".  So if
someone is trying to conform to this draft, your api-catalog pretty well MUST
be at the /.well-known. So maybe it would be simpler to say something like "The
API Catalog MUST be named "api-catalog" in a well-known location as described
by [RFC8615]?

Section 2. "The location (URL) of the API Catalog document is decided…" why the
side-trip into URLs? The URI identifies the api catalog and you use HTTP
requests to retrieve the catalog.

Section 3. I followed the citation on "item" to RFC9264; are you sure that's
the right citation? It didn't teach me anything about "item" in this context,
although the term does appear in an example there.

Section 4. "To account for this scenario, it is RECOMMENDED that:
* the Publisher publish the api-catalog well-known URI at a predictable
location, e.g. example.com/.well-known/api-catalog . * the Publisher also
publish the api-catalog well-known URI at each of their API domains e.g.
apis.example.com/.well-known/api-catalog,
developer.example.net/.well-known/api-catalog etc."

Is the first bullet point useful? The second one is obviously useful, because
if I'm interested in software at $anything.example.$anything, I should be able
to dereference $anything.example.$anything/.well-known/api-catalog

Section 4. "since the physical location (URL) of the API Catalog document is
decided but the publisher...  using HTTP Status Code 308".  I'm wondering what
value suggesting a mechanism adds?  And why 308? As long as I achieve the
result in the previous bullet point (wherever I get it from, it has to be the
same).

Section 7.2. Is it OK in 2024 to bless the use of http: as well as https:?

Section 9. I'm really ignorant of the security issues in this space, but this
section feels a bit short?