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