Reviewer: Mallory Knodel Review result: Not Ready 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. -- last-call mailing list -- last-call@xxxxxxxx To unsubscribe send an email to last-call-leave@xxxxxxxx
