Last Call Review of draft-ietf-httpapi-api-catalog-05
review-ietf-httpapi-api-catalog-05-secdir-lc-salazar-2024-11-09-00

I have reviewed this document as part of the security directorate's
ongoing effort to review all IETF documents being processed by the
IESG.  These comments were written primarily for the benefit of the
security area directors.  Document editors and WG chairs should treat
these comments just like any other last call comments.

Review of draft-ietf-httpapi-api-catalog-05

Reviewer: Joey Salazar
Review Type: SecDir Last Call Review
Document State: In Last Call (ends 2024-11-11)
Reviewed Version: -05

The summary of the review is: Ready with issues

Main Concern: The Security Considerations section needs more input

9.  Security Considerations

Overall, I agree with the OpsDir review which suggested expanding on Access
Controls and Data Sensitivity, and want to add: To help mitigate abuse and
prevent denial-of-service (DoS) attacks on the API catalog endpoint,
rate-limiting measures could be recommended. CORS policies could be suggested
for use on the server to restrict which origins are allowed to access the API
catalog(s). For the internal/private APIs scenario, the text could additionally
mention that metadata exposure should be minimized; a catalog hosted on
developer.example.com should not expose unnecessary metadata about other
domains like internal.example.net. Considerations on how to verify that catalog
content has not been tampered with should be explored.

Lastly, given that RFC8615 expands on some of these concerns and
recommendations, perhaps a note specifically pointing to that section would
help provide valuable insight.

Nits:

Echoing what other reviewers have shared during this LC, I find some parts of
it somewhat harder to digest that could benefit from clearer definition; as a
person not deeply familiar with RFC8615, even after careful reading of section
7 it still remains unclear to me if, in order to prevent "squatting" by using
precise names for a specific application, the examples included in the document
should be `example.com/.well-known/example-api-catalog` or if
`example.com/.well-known/api-catalog` remains applicable. Also, the definition
of 'owner' as opposed to 'publisher' in section 8.2. could benefit from added
context.

Across the document there seems to be a persistence of double spacing between
the end of a sentence and the beginning of the next sentence in the same
paragraph, i.e "choose.  Hence"

Minor corrections:
1.2 Notational Conventions
In "The term "content negotiation" and "status code" are from [HTTP]."
s/term/terms/ In "The term well-known URI is from [RFC8615]." s/well-known
URI/"well-known URI"/

6.  The API Catalog
s/definitions for each API, etc. ./definitions for each API, etc./
s/utiise/utilise/
s/exmple/example/

Other than these, I find good value in the document and look forward to reading
an updated version.

Thank you for your work.