Authors, While reviewing this document during AUTH48, please resolve (as necessary) the following questions, which are also in the XML file.
1) <!-- [rfced] FYI - We have updated the short title of the document, which appears in the running header in the PDF output, as follows. Please review and let us know any objections. Original: api-catalog well-known URI Current: api-catalog: A Well-Known URI --> 2) <!-- [rfced] Please insert any keywords (beyond those that appear in the title) for use on https://www.rfc-editor.org/search. --> 3) <!-- [rfced] Are the goals listed in Section 1.1 specified for api-catalog or for this document? Current: The primary goal is to facilitate the automated discovery of a Publisher's public API endpoints, along with metadata that describes the purpose and usage of each API, by specifying a well-known URI that returns an API catalog document. Perhaps: The primary goal for api-catalog is to facilitate the automated discovery of a Publisher's public API endpoints, along with metadata that describes the purpose and usage of each API, by specifying a well-known URI that returns an API catalog document. Or: The primary goal of this document is to facilitate the automated discovery of a Publisher's public API endpoints, along with metadata that describes the purpose and usage of each API, by specifying a well-known URI that returns an API catalog document. --> 4) <!-- [rfced] We find this sentence difficult to parse. We have updated the text to read as follows. Please let us know any objections. Original: For scenarios where the Publisher "example" is not the authority for a given _.example._ domain then that is made explicit in the text. Current: Scenarios where the Publisher "example" is not the authority for a given _.example._ domain are made explicit in the text. --> 5) <!-- [rfced] May we reformat the bulleted list items in Section 3.1 into paragraph form? Original: 3.1. Using additional link relations * "item" [RFC6573]. When used in an API catalog document, the "item" link relation identifies a target resource that represents an API that is a member of the API catalog. * Other link relations may be utilised in an API catalog to convey metadata descriptions for API links. Perhaps: 3.1. Using Additional Link Relations When used in an API catalog document, the "item" [RFC6573] link relation identifies a target resource that represents an API that is a member of the API catalog. Other link relations may be utilised in an API catalog to convey metadata descriptions for API links. --> 6) <!-- [rfced] Is "As illustration" meant to be "as illustrated" in this context? Would "For example" also work here for simplicity? Original: As illustration, the API catalog document URI of https://www.example.com/my_api_catalog.json can be requested directly, or via a request to https://www.example.com/.well-known/ api-catalog, which the Publisher will resolve to https://www.example.com/my_api_catalog. Perhaps: For example, the API catalog document URI of https://www.example.com/my_api_catalog.json can be requested directly or via a request to https://www.example.com/.well-known/ api-catalog, which the Publisher will resolve to https://www.example.com/my_api_catalog. --> 7) <!-- [rfced] May we split the sentence below into two sentences to improve readability? Original: The API catalog MUST include hyperlinks to API endpoints, and is RECOMMENDED to include useful metadata, such as usage policies, API version information, links to the OpenAPI Specification [OAS] definitions for each API, etc. Perhaps: The API catalog MUST include hyperlinks to API endpoints. It is RECOMMENDED that the API catalog also includes useful metadata, such as usage policies, API version information, links to the OpenAPI Specification [OAS] definitions for each API, etc. --> 8) <!-- [rfced] FYI - We have updated the citation below since Section 5.3 of [HTTP] doesn't appear to mention "content negotiation", while Section 12 of [HTTP] is titled "Content Negotiation". Please review. Original: The Publisher MAY make additional formats available via content negotiation (section 5.3 of [HTTP]) to their /.well-known/api-catalog location. Current: The Publisher MAY make additional formats available via content negotiation (Section 12 of [HTTP]) to their /.well-known/api-catalog location. --> 9) <!-- [rfced] May we rephrase the following sentence for clarity? Original: If the Publisher is not the domain authority for www.example.net - or any third-party domain that hosts any of the Publisher's APIs - then the Publisher MAY include a link in its own API catalog to that third-party domain's API catalog. Perhaps: If the Publisher or any third-party domain that hosts any of the Publisher's APIs is not the domain authority for www.example.net, then the Publisher MAY include a link in its own API catalog to that third-party domain's API catalog. --> 10) <!--[rfced] As this sentence reads awkwardly due to the two instances of "already", may we remove the first one? Original: This grouping may already be implicit where the Publisher has already published their APIs across multiple domains, e.g. at gaming.example.com, iot.example.net, etc. Perhaps: This grouping may be implicit where the Publisher has already published their APIs across multiple domains, e.g., at gaming.example.com, iot.example.net, etc. --> 11) <!-- [rfced] We note that Section 6.3 is titled "Registration of the api-catalog Well-Known URI" and simply states "See Section 7 considerations below." The section that follows immediately is the api-catalog well-known URI IANA registration, thus Section 6.3 seems redundant. May we remove this section to avoid repetition? --> 12) <!-- [rfced] FYI - We have updated "THIS-RFC-URL" to "https://www.rfc-editor.org/info/rfc9727";. Note that this URL will lead to a page that states "RFC 9727 does not exist" until this document is published. --> 13) <!-- [rfced] Please review the following reference. The URL uses the "latest published version", which now takes the reader to version 3.1.1 of [OAS] rather than version 3.1.0 (please note that there has also been a change of authors between versions). Please clarify if you wish for this reference to point to one of these specific versions. If you would like to refer to the latest version, we recommend the following format (with an added annotation). Current: [OAS] Darrel Miller, Ed., Jeremy Whitlock, Ed., Marsh Gardiner, Ed., Mike Ralphson, Ed., Ron Ratovsky, Ed., and Uri Sarid, Ed., "OpenAPI Specification v3.1.0", 15 February 2021, <https://spec.openapis.org/oas/latest>. Perhaps: [OAS] Miller, D., Ed., Andrews, H., Ed., Whitlock, J., Ed., Mitchell, L., Ed., Gardiner, M., Ed., Quintero, M., Ed., Kistler, M., Ed., Handl, R., Ed., and R. Ratovsky, Ed., "OpenAPI Specification v3.1.1", 24 October 2024, <https://spec.openapis.org/oas/v3.1.1.html>. Latest version available at <https://spec.openapis.org/oas/latest.html>. --> 14) <!-- [rfced] Please review the following reference. The date provided for this reference is 15 September 2020, but the URL lists a date of 9 January 2020. We have updated this reference to use that date. There are also more recent versions of this specification (see https://apisjson.org/). The latest version was released on 6 November 2024 (see https://apisjson.org/format/apisjson_0.19.txt). Would you like us to update the URL to use the most current version and date for this reference? Current: [APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 9 January 2020, <http://apisjson.org/format/apisjson_0.16.txt>. Perhaps: [APIsjson] Lane, K. and S. Willmott, "API Discovery Format", 6 November 2024, <https://apisjson.org/format/apisjson_0.19.txt>. Latest version available at <https://apisjson.org/>. --> 15) <!-- [rfced] Please review the reference entry for [RESTdesc]. It uses the same URL as [APIsjson] (https://apisjson.org/format/apisjson_0.16.txt). We found the following the URL, which appears to match some of the original reference information provided: https://restdesc.org/. Please provide an updated reference entry for [RESTdesc]. Current: [RESTdesc] Ruben Verborgh, Erik Mannens, Rick Van de Walle, and Thomas Steiner, "RESTdesc", 15 September 2023, <http://apisjson.org/format/apisjson_0.16.txt>. --> 16) <!-- [rfced] May we rephrase the following section title to avoid using RFC 8615 as an adjective? Also, we have updated the RFC number to 8631 as we belive this was the intended RFC. Original: A.1. Using Linkset with RFC8615 relations Perhaps: A.1. Using Linkset with Link Relations Defined in RFC 8631 --> 17) <!-- [rfced] We have updated the following bulleted list into a definition list for a more cohesive presentation. Please let us know any objections. Original: * "service-desc", used to link to a description of the API that is primarily intended for machine consumption (for example the [OAS] specification YAML or JSON file). * "service-doc", used to link to API documentation that is primarily intended for human consumption (an example of human-readable documentation is the IETF Internet-Draft submission API instructions (https://datatracker.ietf.org/api/submission)). * "service-meta", used to link to additional metadata about the API, and is primarily intended for machine consumption. * "status", used to link to the API status (e.g. API "health" indication etc.) for machine and/or human consumption. Current: "service-desc": Used to link to a description of the API that is primarily intended for machine consumption (for example, the [OAS] specification YAML or JSON file). "service-doc": Used to link to API documentation that is primarily intended for human consumption (an example of human-readable documentation is the IETF Internet-Draft submission API instructions (https://datatracker.ietf.org/api/submission)). "service-meta": Used to link to additional metadata about the API and is primarily intended for machine consumption. "status": Used to link to the API status (e.g., API "health" indication) for machine and/or human consumption. --> 18) <!-- [rfced] We note that the document uses single quotes (') and double quotes (") inconsistently. For example, "api-catalog" and "example" appear multiple times using both single and double quotes. Is this intentional? If there are no objections, may we replace all instances of single quotes with double quotes for consistency? --> 19) <!-- [rfced] FYI - We have added expansions for the following abbreviations per Section 3.6 of RFC 7322 ("RFC Style Guide"). Please review each expansion in the document carefully to ensure correctness. Cross-Origin Resource Sharing (CORS) Fully Qualified Domain Name (FQDN) Top-Level Domain (TLD) --> 20) <!-- [rfced] We updated artwork to sourcecode in Appendix A.1, A.2, and A.4 to match the sourcecode element in Section 5.1. Please confirm that this is correct. Please consider whether the "type" attribute for these sourcecode elements should be set to "json", "pseudocode", or something else. The current list of preferred values for "type" is available at <https://www.rfc-editor.org/rpc/wiki/doku.php?id=sourcecode-types>. If the current list does not contain an applicable type, feel free to suggest additions for consideration. Note that it is also acceptable to leave the "type" attribute not set. --> 21) <!-- [rfced] Please review the "Inclusive Language" portion of the online Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language> and let us know if any changes are needed. Updates of this nature typically result in more precise language, which is helpful for readers. Note that our script did not flag any words in particular, but this should still be reviewed as a best practice. --> Thank you. RFC Editor/mc/ap On Jun 2, 2025, at 4:57 PM, rfc-edi...@rfc-editor.org wrote: *****IMPORTANT***** Updated 2025/06/02 RFC Author(s): -------------- Instructions for Completing AUTH48 Your document has now entered AUTH48. Once it has been reviewed and approved by you and all coauthors, it will be published as an RFC. If an author is no longer available, there are several remedies available as listed in the FAQ (https://www.rfc-editor.org/faq/). You and you coauthors are responsible for engaging other parties (e.g., Contributors or Working Group) as necessary before providing your approval. Planning your review --------------------- Please review the following aspects of your document: * RFC Editor questions Please review and resolve any questions raised by the RFC Editor that have been included in the XML file as comments marked as follows: <!-- [rfced] ... --> These questions will also be sent in a subsequent email. * Changes submitted by coauthors Please ensure that you review any changes submitted by your coauthors. We assume that if you do not speak up that you agree to changes submitted by your coauthors. * Content Please review the full content of the document, as this cannot change once the RFC is published. Please pay particular attention to: - IANA considerations updates (if applicable) - contact information - references * Copyright notices and legends Please review the copyright notice and legends as defined in RFC 5378 and the Trust Legal Provisions (TLP – https://trustee.ietf.org/license-info). * Semantic markup Please review the markup in the XML file to ensure that elements of content are correctly tagged. For example, ensure that <sourcecode> and <artwork> are set correctly. See details at <https://authors.ietf.org/rfcxml-vocabulary>. * Formatted output Please review the PDF, HTML, and TXT files to ensure that the formatted output, as generated from the markup in the XML file, is reasonable. Please note that the TXT will have formatting limitations compared to the PDF and HTML. Submitting changes ------------------ To submit changes, please reply to this email using ‘REPLY ALL’ as all the parties CCed on this message need to see your changes. The parties include: * your coauthors * rfc-edi...@rfc-editor.org (the RPC team) * other document participants, depending on the stream (e.g., IETF Stream participants are your working group chairs, the responsible ADs, and the document shepherd). * auth48archive@rfc-editor.org, which is a new archival mailing list to preserve AUTH48 conversations; it is not an active discussion list: * More info: https://mailarchive.ietf.org/arch/msg/ietf-announce/yb6lpIGh-4Q9l2USxIAe6P8O4Zc * The archive itself: https://mailarchive.ietf.org/arch/browse/auth48archive/ * Note: If only absolutely necessary, you may temporarily opt out of the archiving of messages (e.g., to discuss a sensitive matter). If needed, please add a note at the top of the message that you have dropped the address. When the discussion is concluded, auth48archive@rfc-editor.org will be re-added to the CC list and its addition will be noted at the top of the message. You may submit your changes in one of two ways: An update to the provided XML file — OR — An explicit list of changes in this format Section # (or indicate Global) OLD: old text NEW: new text You do not need to reply with both an updated XML file and an explicit list of changes, as either form is sufficient. We will ask a stream manager to review and approve any changes that seem beyond editorial in nature, e.g., addition of new text, deletion of text, and technical changes. Information about stream managers can be found in the FAQ. Editorial changes do not require approval from a stream manager. Approving for publication -------------------------- To approve your RFC for publication, please reply to this email stating that you approve this RFC for publication. Please use ‘REPLY ALL’, as all the parties CCed on this message need to see your approval. Files ----- The files are available here: https://www.rfc-editor.org/authors/rfc9727.xml https://www.rfc-editor.org/authors/rfc9727.html https://www.rfc-editor.org/authors/rfc9727.pdf https://www.rfc-editor.org/authors/rfc9727.txt Diff file of the text: https://www.rfc-editor.org/authors/rfc9727-diff.html https://www.rfc-editor.org/authors/rfc9727-rfcdiff.html (side by side) Diff of the XML: https://www.rfc-editor.org/authors/rfc9727-xmldiff1.html Tracking progress ----------------- The details of the AUTH48 status of your document are here: https://www.rfc-editor.org/auth48/rfc9727 Please let us know if you have any questions. Thank you for your cooperation, RFC Editor -------------------------------------- RFC9727 (draft-ietf-httpapi-api-catalog-08) Title : api-catalog: a well-known URI and link relation to help discovery of APIs Author(s) : K. Smith WG Chair(s) : Darrel Miller, Rich Salz Area Director(s) : Gorry Fairhurst, Mike Bishop -- auth48archive mailing list -- auth48archive@rfc-editor.org To unsubscribe send an email to auth48archive-le...@rfc-editor.org
