search

ietf-wg-httpapi / api-catalog

For writing the draft-ietf-httpapi-api-catalog draft
Other
2 stars 2 forks source link

SECDIR Last Call Review: Nits #47

Open Kevsy opened 5 days ago

Kevsy commented 5 days ago

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"/

  1. The API Catalog s/definitions for each API, etc. ./definitions for each API, etc./ s/utiise/utilise/
richsalz commented 5 days ago

Do not bother with the 'squatting' issue. Perhaps just say in the security considerations, that the registration of names and policy about that is out of scope for this document. ?