Skip to main content

Shepherd writeup
draft-ietf-httpapi-api-catalog

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

Back