[ADP-51] API Review

reviewing phase 1

This article does not cleary specify the process of reviewing an API document yet.

Guidance

Review Scope

• SHOULD review the overall API design, resource model, endpoint structure, and naming conventions.
• MAY review security considerations, error handling, and documentation.
• SHOULD NOT focus excessively on implementation details unless they directly impact the public API interface.
• SHOULD seek design patterns on the ADP site.

Review Standards

• SHOULD assess adherence to organization's API design principles and best practices.
• MAY consider API usability, consistency, and scalability.
• SHOULD verify if the API fulfills its intended purpose and meets target audience needs.

Feedback Style

• SHOULD provide specific, actionable feedback, not general criticism.
• MAY use suggestive language (e.g., "consider", "might") rather than imperative language.
• SHOULD balance identifying issues with acknowledging good design decisions.

Resolving Disagreements

• SHOULD resolve disagreements through open discussion, focusing on end-user needs.
• MAY seek input from higher-level decision-makers if consensus cannot be reached.

Example Review Comments

1. "Consider more descriptive resource names. 'items' might be too vague; can we explore more precise terminology?"

2. "The response structure looks clear. Consider adding pagination support for potentially large datasets."

3. "Authentication method seems suitable. We should discuss authorization handling for different user roles."

FAQ

Who typically designs APIs and how?

API design is a collaborative effort involving stakeholders like software architects, developers, product managers, and domain experts. The process typically starts with identifying requirements, goals, target audience, purpose, and constraints. Design techniques may include domain-driven design, RESTful principles, or GraphQL schema design.

Does my API need to be reviewed?

• COMPONENT_INTERNAL APIs (team-specific): No extra review needed outside the team.
• BUSINESS_UNIT_INTERNAL APIs (organization-specific): Recommended review by organization's technical lead.
• COMPANY_INTERNAL APIs (company-wide): Expected review by an API design principle expert.
• PARTNER_EXTERNAL APIs (specific partner): Recommended to fulfill as many principles as possible during design.
• PUBLIC_EXTERNAL APIs (non-specific): Highly recommended review before public release.

Who should be the API reviewer?

An API reviewer should have expertise in API design and best practices, understand the organization's API design principles, and provide valuable feedback on various API aspects.

What if the URL design is difficult to decide?

Involve the API reviewer in the decision-making process. They can provide guidance based on design principles, best practices, and target audience needs.

How can we ensure consistency across multiple APIs?

Refer to this site's API Design Principles for comprehensive guidelines and best practices to maintain uniformity in API design.

What if my API design case is not covered by any ADP?

If your specific API design case is not covered by existing ADPs (API Design Principles):

• Consult with your team and API governance experts to determine the best approach.
• Document your decision-making process and rationale.
• Consider proposing a new ADP if the case is likely to recur in future projects.
• Ensure your solution aligns with general API design best practices and your organization's overall API strategy.

Can I establish team specific principles?

Yes, teams can establish specific principles, but with some considerations:

• Team-specific principles SHOULD NOT contradict organization-wide ADPs.
• They SHOULD be documented and communicated clearly within the team.
• Consider if these principles could be valuable for other teams or the entire organization.
• Regularly review and update team-specific principles to ensure they remain relevant and aligned with broader organizational goals.

What if I need to violate the standard?

If you need to violate an established API design standard:

• Clearly document the reasons for the violation and its potential impacts.
• Seek approval from API governance stakeholders or relevant decision-makers.
• Consider if this violation indicates a need to revise or expand existing standards.
• Implement the non-standard solution as an exception, not a new rule.
• Plan for potential future alignment with standards, if possible.
• Ensure the violation doesn't compromise security, scalability, or maintainability of the API.