api-catalog: a well-known URI and link relation to help discovery of APIs
draft-ietf-httpapi-api-catalog-08
Yes
Francesca Palombini
No Objection
Jim Guichard
Paul Wouters
Zaheduzzaman Sarker
Note: This ballot was opened for revision 06 and is now closed.
Francesca Palombini
Yes
Murray Kucherawy
Yes
Comment
(2024-12-04 for -06)
Sent
I recommend dropping all the SHOULDs in Section 5.4. They're all redundant to the RECOMMENDED. Apart from that, all of the SHOULDs prior to Section 8 are naked in the sense that it's not clear to me why they're not MUST or MAY. What guidance can we offer to implementers about when it might be legitimate to deviate from what the SHOULD says? What's the protocol or operational impact of [not] doing so?
Deb Cooley
No Objection
Comment
(2024-12-03 for -06)
Not sent
Thanks to Joey Salazar for her secdir review!
Erik Kline
No Objection
Comment
(2024-11-29 for -06)
Sent
# Internet AD comments for draft-ietf-httpapi-api-catalog-06 CC @ekline * comment syntax: - https://github.com/mnot/ietf-comments/blob/main/format.md * "Handling Ballot Positions": - https://ietf.org/about/groups/iesg/statements/handling-ballot-positions/ ## Nits ### S5.1, S5.5 * "./well-known/api-catalog" -> "/.well-known/api-catalog" ? * "https://www.example.net/./well-known/api-catalog" -> "https://www.example.net/.well-known/api-catalog" ? I may have misunderstood if these are intentional, as opposed to simply looking like typos...
Gunter Van de Velde
No Objection
Comment
(2024-11-29 for -06)
Sent
# Gunter Van de Velde, RTG AD, comments for draft-ietf-httpapi-api-catalog-06 # Thanks for this document. It outlines a useful procedure. # I only got one non-blocking minor comment. In the document sometimes "API catalog" is used and sometimes "API Catalog ". I suspect that a consistent upper/lower case for catalog is intended?
Jim Guichard
No Objection
Orie Steele
No Objection
Comment
(2024-12-04 for -06)
Sent
# Orie Steele, ART AD, comments for draft-ietf-httpapi-api-catalog-06 CC @OR13 * line numbers: - https://author-tools.ietf.org/api/idnits?url=https://www.ietf.org/archive/id/draft-ietf-httpapi-api-catalog-06.txt&submitcheck=True * comment syntax: - https://github.com/mnot/ietf-comments/blob/main/format.md * "Handling Ballot Positions": - https://ietf.org/about/groups/iesg/statements/handling-ballot-positions/ ## Almost a Discuss There is an open expert review comment for -06 and IANA is listed as not OK. I read the expert's comment and I think I agree with them. From https://datatracker.ietf.org/doc/html/rfc8288#section-2.1.1.1 ``` o *Description*: A short English description of the type's semantics. It SHOULD be stated in terms of the relationship between the link context and link target. ``` I believe that context was used correctly in -05, and ... I can see from the list there are plans in the works to correct this: https://mailarchive.ietf.org/arch/msg/httpapi/w8VtmpTdXLah8lfyGKkOzptOOLo/ ## Comments Thanks to Tim Bray for the ARTART Review, and the the authors for addressing his comments. As a general comment there appear to be a lot of BCP14 SHOULD's that are really "you ought to", and that do not have an impact on interoperability or security, I've opted not to ask the question "when can this SHOULD be ignored" on each of them. ### Why is HEAD not mandatory? ``` 186 * SHOULD resolve an HTTPS HEAD request to /.well-known/api-catalog 187 with a response including a Link header with the relation(s) 188 defined in Section 3 ``` When can this SHOULD be ignored? ### Which URL? ``` 259 * A linkset in JSON Document format (section 4.2 of [RFC9264]) of 260 API endpoints and information to facilitate API usage. The 261 linkset SHOULD include a profile parameter (section 5 of 262 [RFC9264]) with a Profile URI [RFC7284] value of 'THIS-RFC-URL' to 263 indicate the linkset is representing an API Catalog document as 264 defined above. Appendix A includes example API Catalog documents 265 based on the linkset format. ``` ``` 550 RFC Editor's Note: IANA is kindly requested to replace all instances 551 of THIS-RFC and THIS-RFC-URL with the actual RFC number/URL once 552 assigned. ``` Maybe its obvious but I assume this is not a link to the datatracker? ### Informative section with BCP14 RECOMMENDED? ``` 662 This section is informative and provides and example of an API 663 Catalog document using the RECOMMENDED linkset format. ``` Also isn't linkset mandatory to support?
Paul Wouters
No Objection
Zaheduzzaman Sarker
No Objection
Éric Vyncke
No Objection
Comment
(2024-11-28 for -06)
Sent
# Éric Vyncke, INT AD, comments for raft-ietf-httpapi-api-catalog-06 Thank you for the work put into this document. As a frequent API user, this can only help developpers, thank you. Please find below some non-blocking COMMENT points (but replies would be appreciated even if only for my own education). Special thanks to Darrel Miller for the shepherd's detailed write-up including the WG consensus *and* the justification of the intended status. I hope that this review helps to improve the document, Regards, -éric # COMMENTS (non-blocking) ## Abstract In `APIs published by a given organisation or individual`, I wonder how can an individual publish an API, their server can of course but a human being ? What about simply "published API" ? ## Section 1 Very similar to my above comment, `An organisation or individual may ` ;-) Why not simply "application" or "server" ? ## Section 1.1 Suggest to add `human-readable documentation` in the examples of the appendix. ## Section 5.3 Wrong reference in `Section 4.1 below ` as 4.1 cannot be 'below' section 5.3 ;-) ## Section 4 I find this section really/too much open for a proposed standard as `Some suitable API Catalog document formats include` is followed by 6 possible ways and this list is not even exhaustive. Does it mean that implementations must support all ways ? All references in the bulleted list should be normative and not informative. ## Section 5.4 s/Heath/Availability/ as health also covers integrity and applicability. ## For the IETF tools-team Not for the authors, but it would be nice to have https://datatracker.ietf.org/.well-known/api-catalog ;-)