Reviewer: Tina Tsou
Review result: Has Nits
Review of draft-ietf-httpapi-api-catalog-05
Reviewer: Tina Tsou (Ting ZOU)
Review Type: OpsDir Last Call Review
Document State: In Last Call (ends 2024-11-11)
Reviewed Version: -05
Summary
The document draft-ietf-httpapi-api-catalog provides a specification for a
shared API catalog intended to facilitate the discovery of HTTP APIs and their
associated metadata. This review will focus on the operational and management
aspects of the draft, providing feedback on its readiness, potential
improvements, and any issues noted.
Review Result: Has Issues
Operational Considerations
The document introduces a shared catalog for HTTP APIs, which can be useful for
developers and operators to discover APIs within a network or organization.
However, a few operational considerations need more emphasis:
1. Scalability: The document should address how the API catalog would behave in
large-scale deployments. How does it ensure efficiency when managing thousands
of APIs across multiple domains? Adding scalability guidelines or recommended
practices would help operators make informed decisions when deploying this
catalog.
2. Monitoring and Maintenance: Operational best practices for monitoring the
catalog’s performance, health, and usage should be elaborated on. How are
issues detected, such as stale API entries or incorrect metadata? Adding a
section for monitoring metrics and maintenance workflows would enhance the
usability for operations teams.
Management Considerations
1. Metadata Integrity: Ensuring the integrity of metadata is critical,
especially as the catalog grows. Guidance on validation processes, error
handling, and the removal of outdated or incorrect entries would be beneficial.
2. Interoperability: Since many organizations already use proprietary or custom
API management solutions, it would be helpful to provide more details on how
this catalog can interoperate with existing API management frameworks. This
could include integration examples or guidelines for mapping catalog entries to
existing systems.
Security Considerations
The security considerations are addressed in the draft, but a few operational
scenarios could benefit from additional clarification:
1. Access Control: It would be beneficial to include examples or best practices
on how access control to the catalog should be implemented. What roles or
permissions are necessary to ensure that only authorized personnel can add or
modify API entries?
2. Data Sensitivity: The draft does not clearly cover scenarios where the
metadata itself may be sensitive (e.g., internal-only APIs). How can sensitive
API entries be protected from accidental exposure?
Nits
- Section 3.1: Consider rephrasing for better clarity; the current phrasing is
slightly ambiguous when discussing “API registration requirements.” -
Formatting: A few sections have inconsistent heading levels that could be
unified for better readability. - Grammar: Minor grammatical errors in Section
5.2, such as missing articles ("the API" instead of "API").
Conclusion
The draft is a promising specification for creating a shared API catalog, which
could greatly simplify API discovery across teams and organizations. However,
addressing the mentioned operational concerns and elaborating on security
practices would strengthen the document and improve its operational readiness.
I recommend updating the draft to include more specific operational guidelines
to address scalability, monitoring, and security considerations effectively.
--
last-call mailing list -- last-call@xxxxxxxx
To unsubscribe send an email to last-call-leave@xxxxxxxx
