api-catalog: a well-known URI and link relation to help discovery of APIs
draft-ietf-httpapi-api-catalog-08

Additional link relations expert comments after updates made in response to expert feedback to the "description" field change from "context" to "target domain" in -06, Section 7.2:

"Context resource" is a new term that isn't defined in the Web linking framework -- I'd suggest:

Description: The link target refers to a list of APIs available from the publisher of the link context.

Or simply

Description: Refers to a list of APIs available from the publisher of the link context.

[Ballot comment]
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?

[Ballot comment]
# 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?

Additional link relations expert comments after "description" field change from "context" to "target domain" in -06, Section 7.2: "This seems problematic, in that it allows any link on the Internet to assert an API catalogue for a given URI. At the very least some security considerations about consuming such an assertion should be outlined.

Furthermore, it's a deviation from the Web Linking specification, which defines a link as involving a context, a target, and a relation type. The relation type definition can't modify this relationship. As such I suspect that this specification isn't defining a link relation per se, it's defining _something else_."

[Ballot comment]
# 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...

[Ballot comment]
# 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?

[Ballot comment]

# É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 ;-)

IESG/Authors/WG Chairs:

IANA has completed its review of draft-ietf-httpapi-api-catalog-05. If any part of this review is inaccurate, please let us know.

IANA understands that, upon approval of this document, there are three actions which we must complete.

First, in the Well-Known URIs registry located at:

https://www.iana.org/assignments/well-known-uris/

a single new registration will be made as follows:

URI Suffix: api-catalog
Reference: [ RFC-to-be ]
Status: permanent
Change Controller: IETF
Related Information: The "api-catalog" documents obtained from the same host using the HTTP and HTTPS protocols (using default ports) MUST be identical.

As this document requests a registration in an Expert Review or Specification Required (see RFC 8126) registry, we have initiated the required Expert Review via a separate request. This review must be completed before the document's IANA state can be changed to "IANA OK."

Second, in the Link Relation Types registry in the Link Relations registry group located at:

https://www.iana.org/assignments/link-relations/

a single new registration will be made as follows:

Relation Name: api-catalog
Description: The link target identifies a catalog of APIs published by the owner of the link context.
Reference: [ RFC-to-be ]
Notes:

As this also requests a registration in an Expert Review or Specification Required (see RFC 8126) registry, we have initiated the required Expert Review via a separate request. This review must be completed before the document's IANA state can be changed to "IANA OK."

Third, in the Profile URIs registry located at:

https://www.iana.org/assignments/profile-uris/

a single new registration will be made as follows:

Profile URI: [ RFC-to-be ]-URL
Common Name: API Catalog
Description: A profile URI to request or signal a linkset representing an API Catalog.
Reference: [ RFC-to-be ]

IANA understands [ RFC-to-be ]-URL to be the concatenation of the finished RFC number and the characters "-RFC"

We understand that these are the only actions required to be completed upon approval of this document.

NOTE: The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

David Dong
IANA Services Sr. Specialist

The Well-Known URIs registration has been approved, with a request: "Approved, but the 'related information' should be pulled out into the text of the specification, not be in the registry (as it contains a RFC2119 requirement)."

Issues with the Link Relations registration: "(1) Regarding the link relation definition "The link target identifies a catalog of APIs published by the owner of the link context." Since the only relationship between link target and link context is this 'ownership' I think it should be more precise what 'owner' means - I do not find any definition of owner in the draft. Can you express that in a well defined term? In addition, is there any other relationship beyond 'same owner' between link target and context? (2) I think the use of MUST is too restrictive here because it limits evolution over time by establishing a promise that is likely not going to be kept - so clients have to prepare for unexpected situations either way. I suggest changing it to SHOULD."

(1) Regarding the link relation definition

"The link target identifies a catalog of APIs published by the owner of the link context."

Since the only relationship between link target and link context is this 'ownership' I think it should be more precise what 'owner' means - I do not find any definition of owner in the draft. Can you express that in a well defined term?

In addition, is there any other relationship beyond 'same owner' between link target and context?

(2) I think the use of MUST is too restrictive here because it limits evolution over time by establishing a promise that is likely not going to be kept - so clients have to prepare for unexpected situations either way. I suggest changing it to SHOULD.

The following Last Call announcement was sent out (ends 2024-11-11):

From: The IESG
To: IETF-Announce
CC: darrel@tavis.ca, draft-ietf-httpapi-api-catalog@ietf.org, francesca.palombini@ericsson.com, httpapi-chairs@ietf.org, httpapi@ietf.org
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (api-catalog: a well-known URI and link relation to help discovery of APIs) to Proposed Standard


The IESG has received a request from the Building Blocks for HTTP APIs WG
(httpapi) to consider the following document: - 'api-catalog: a well-known
URI and link relation to help discovery of
  APIs'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2024-11-11. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This document defines the "api-catalog" well-known URI and link
  relation.  It is intended to facilitate automated discovery and usage
  of the APIs published by a given organisation or individual.  A
  request to the api-catalog resource will return a document providing
  information about, and links to, the publisher's APIs.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-httpapi-api-catalog/



No IPR declarations have been submitted directly on this I-D.


The document contains these normative downward references.
See RFC 3967 for additional information:
    rfc7284: The Profile URI Registry (Informational - Independent Submission stream)

# Document Shepherd Write-Up for draft-ietf-httpapi-api-catalog-02

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

I have observed broad consensus across the working group for this document.  There have been a significant number of comments and suggestions, and the author has addressed them all.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

There was concern raised by some members of the working group about the ability to support identifying different kinds of APIs.  For example, whether those APIs respected REST constraints for resource discovery, or if they used static API description documents.  The author demonstrates support for a broad set of scenarios with examples in the document.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

Nobody has threatened an appeal or indicated extreme discontent.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There are not existing implementations that I am aware of.  There has been expression of interest to implement.

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

This document leans heavily on prior work such as LinkSet (RFC9264), Profiles (RFC7284) and Well Known URIs (RFC8615). The authors of RFC9264 have provided extensive feedback on the document. The use of a profile URI and the well known URI are not controversial and would not likely benefit from further review.  The use of the Well Known URI is consistent with the guidance in BCP56.


6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

The document requires registering the Well-Known URI according to the process described here https://www.rfc-editor.org/rfc/rfc8615.html#section-3.1
The document also requires registering the profile URI according to the process described here https://www.rfc-editor.org/rfc/rfc7284.html#section-5.1
The document requires registering the link relation type according to the process described here https://www.rfc-editor.org/rfc/rfc8288.html#section-2.1.1.1

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

It does not.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

IdNits tool was run on the document.
HTML validator was used to verify the HTML examples.
JSON Validator was used to verify the JSON examples.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

This document is needed. A significant portion of the internet's traffic targets APIs, there are over a million API descriptions published on the web and yet there is no standardized way to discover these APIs.  The search engines do not specifically index APIs or their descriptions. It is clearly written, it finds the right balance between being prescriptive and being flexible.  It leverages two existing discovery mechanisms and provides a range of formats for API producers to use in order to encourage adoption, as well as providing a recommended format for future alignment.
This document is ready to be handed off to the responsible Area Director.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

The ART and Security areas are relevant to this document. The common issues have been reviewed and there are no applicable issues that need to be addressed.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed Standard.  Datatracker has been updated to reflect this. This is appropriate as it defines a new Well-Known URI, a new Link Relation Type and a Profile URI.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

a) Reference to RFC6415 as the registry of well-known URIs should be to RFC8615

b) ** There are 5 instances of too long lines in the document, the longest one
    being 70 characters in excess of 72.

c) ** Downref: Normative reference to an Informational RFC: RFC 7284

d) Section 3 example contains extra \ after the http in the location header
e) Section 3 example Link header appears to contain an extra period at the end of the URI
f) Section 3 example contains an invalid self closing p tag that should be an opening tag to match the closing tag.
g) Section 4 example response contains extra \ after the http in the location header
h) Appendix A.2 example is missing a comma after the second item in the array

Issues other than b and c are proposed in this PR https://github.com/ietf-wg-httpapi/api-catalog/pull/3

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

There is a Normative reference to an Informational RFC: [RFC 7284](https://www.rfc-editor.org/rfc/rfc7284.html).  Considering this reference is to registration procedures for a profile URI, it may not need to be normative in this document as it is not required to implement the specification.  Looking for guidance here.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

None

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

None, assuming that RFC7284 can become an Informative reference

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

The IANA considerations section contains three registrations that are consistent with the document and accurately reference the appropriate IANA registries (Except for the previously referenced use of RFC6415 instead of RFC8615).

The well known URI registration is missing the entry for Change Controller and status.  The document should specify the IETF as the Change Controller. The status should be permanent.


21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

This document does not  introduce any new IANA registries.

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/

# Document Shepherd Write-Up for draft-ietf-httpapi-api-catalog-02

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

I have observed broad consensus across the working group for this document.  There have been a significant number of comments and suggestions, and the author has addressed them all.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

There was concern raised by some members of the working group about the ability to support identifying different kinds of APIs.  For example, whether those APIs respected REST constraints for resource discovery, or if they used static API description documents.  The author demonstrates support for a broad set of scenarios with examples in the document.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

Nobody has threatened an appeal or indicated extreme discontent.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

There are not existing implementations that I am aware of.  There has been expression of interest to implement.

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

This document leans heavily on prior work such as LinkSet (RFC9264), Profiles (RFC7284) and Well Known URIs (RFC8615). The authors of RFC9264 have provided extensive feedback on the document. The use of a profile URI and the well known URI are not controversial and would not likely benefit from further review.  The use of the Well Known URI is consistent with the guidance in BCP56.


6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

The document requires registering the Well-Known URI according to the process described here https://www.rfc-editor.org/rfc/rfc8615.html#section-3.1
The document also requires registering the profile URI according to the process described here https://www.rfc-editor.org/rfc/rfc7284.html#section-5.1
The document requires registering the link relation type according to the process described here https://www.rfc-editor.org/rfc/rfc8288.html#section-2.1.1.1

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

It does not.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

IdNits tool was run on the document.
HTML validator was used to verify the HTML examples.
JSON Validator was used to verify the JSON examples.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

This document is needed. A significant portion of the internet's traffic targets APIs, there are over a million API descriptions published on the web and yet there is no standardized way to discover these APIs.  The search engines do not specifically index APIs or their descriptions. It is clearly written, it finds the right balance between being prescriptive and being flexible.  It leverages two existing discovery mechanisms and provides a range of formats for API producers to use in order to encourage adoption, as well as providing a recommended format for future alignment.
This document is ready to be handed off to the responsible Area Director.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

The ART and Security areas are relevant to this document. The common issues have been reviewed and there are no applicable issues that need to be addressed.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed Standard.  Datatracker has been updated to reflect this. This is appropriate as it defines a new Well-Known URI, a new Link Relation Type and a Profile URI.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

a) Reference to RFC6415 as the registry of well-known URIs should be to RFC8615

b) ** There are 5 instances of too long lines in the document, the longest one
    being 70 characters in excess of 72.

c) ** Downref: Normative reference to an Informational RFC: RFC 7284

d) Section 3 example contains extra \ after the http in the location header
e) Section 3 example Link header appears to contain an extra period at the end of the URI
f) Section 3 example contains an invalid self closing p tag that should be an opening tag to match the closing tag.
g) Section 4 example response contains extra \ after the http in the location header
h) Appendix A.2 example is missing a comma after the second item in the array

Issues other than b and c are proposed in this PR https://github.com/ietf-wg-httpapi/api-catalog/pull/3

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

There is a Normative reference to an Informational RFC: [RFC 7284](https://www.rfc-editor.org/rfc/rfc7284.html).  Considering this reference is to registration procedures for a profile URI, it may not need to be normative in this document as it is not required to implement the specification.  Looking for guidance here.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

None

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

None, assuming that RFC7284 can become an Informative reference

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

The IANA considerations section contains three registrations that are consistent with the document and accurately reference the appropriate IANA registries (Except for the previously referenced use of RFC6415 instead of RFC8615).

The well known URI registration is missing the entry for Change Controller and status.  The document should specify the IETF as the Change Controller. The status should be permanent.


21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

This document does not  introduce any new IANA registries.

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/

There was consensus at the end of April to move this to WGLC.  We're starting a two-week working group review, before we ask our AD (Francesca) to review it and pass it to the IESG.