Last Call Review of draft-ietf-httpapi-api-catalog-05
review-ietf-httpapi-api-catalog-05-genart-lc-knodel-2024-11-13-00

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<https://wiki.ietf.org/en/group/gen/GenArtFAQ>.

Document: draft-ietf-httpapi-api-catalog-??
Reviewer: Mallory Knodel
Review Date: 2024-11-13
IETF LC End Date: 2024-11-11
IESG Telechat date: Not scheduled for a telechat

Summary: This specification is very useful and it's especially nice that it is
short and to the point. My overall review is to ensure that the advice in this
important document is understandable and clear.

Major issues: None.

Minor issues: There are two main issues that if resolved will help with the
document conceptually:

 * www.example.com vs example.com vs example.net-- these examples appear
 arbitrarily different, eg it is not clear when the subdomain or the tld bears
 upon the advice and when it is just a conventional oversight. Please be
 thoroughly consistent throughout and if there is a change, explicitly state
 why that change is important to implementation.

 * Relatedly, in sections 2-4 the advice could be clearer.

 ** 1) section 4 should build upon section 2, specifically remove the first
 bullet point from section 4 because it is redundant to section 2 and would
 give readers the wrong idea that the advice in section 2 needs to change
 materially on this point (it seems to me that it doesn't).

 ** 2) section 4 neglects to say what should happen if the Publisher is *not*
 the domain authority for example.net:

   If the Publisher is also the domain authority for example.net, which
   also hosts a selection of their APIs, then a request to
   www.example.net/.well-known/api-catalog SHOULD return a redirect as
   follows.

 * Lastly perhaps consider the use of HTTP(S), a new convention-- I haven't
 seen this usage anywhere else in documentation. You could use HTTP/HTTPS, or
 you might controversially perhaps use just HTTPS and describe in the security
 considerations why you are not being explicit about the use of HTTP (given we
 have moved on from this standard 20 years ago).

Nits/editorial comments: There are several punctuation issues throughout. In
the last paragraph of section 6 it appears a bulleted list hasn't rendered
properly. The stacked head in section 7 should end with a complete sentence,
perhaps listing the various subsections rather than ending with a colon.