[ADP-46] API Guideline Exception

Each team or business unit may have specific considerations or unique requirements when designing APIs. The role of ADP (API Design Principles) is to assist and support each API designer in creating effective and more consistent APIs, rather than as a strict rule enforcer. ADP, as a resource, provides best practices and recommendations to facilitate the design process, but does not imply strict regulation.

We understand that for APIs with an audience level less than COMPONENT_INTERNAL, it may be necessary to make minor adjustments to established conventions to meet the unique needs of specific components or internal system usage. These adjustments should be reasonable, as long as they do not compromise the overall integrity, maintainability, or interoperability of the API. This flexibility aims to enable teams to meet their specific needs while still adhering to the core principles of good API design.

For APIs with an audience level of PARTNER_EXTERNAL, adjustments are also needed to meet the requirements of partners, ensuring that the API can meet the needs of partners.

Exception Process

1. SHOULD document the specific guideline being exempted. See ADP-757
2. SHOULD provide a clear rationale for the exception
3. SHOULD outline any potential risks or impacts
4. DRAFT SHOULD submit for review to the API governance team
5. MAY obtain approval before implementing the exception

Importance of Documentation

When an exception is granted, it's crucial to thoroughly document the deviation, including the reasoning behind it and any potential implications. This documentation should be easily accessible to all relevant stakeholders.

Regular Review

Exceptions should be reviewed periodically to ensure they remain necessary and don't negatively impact the overall API ecosystem. This review process helps maintain consistency and quality over time.

Example Scenarios for Acceptable Exceptions

• Legacy system integration requiring non-standard data formats
• Performance optimizations for high-volume internal APIs
• Compliance with specific regulatory requirements
• MISC

Scope of COMPONENT_INTERNAL

COMPONENT_INTERNAL APIs are those used exclusively within a specific component or system, not exposed to external consumers or other internal teams. These APIs have a limited scope and audience, which may justify certain deviations from standard guidelines.

When considering API guideline exceptions, keep the following points in mind:

1. Exceptions should be exceptional, not routine. In most cases, following standard guidelines will produce the best results.

2. Carefully weigh the benefits and potential risks of deviating from the guidelines. Ensure that the exception truly adds value for your specific use case.

3. Transparency is crucial. Make sure all relevant parties understand the exception and its rationale.

4. Regularly reassess exceptions. Over time, the original reasons may no longer apply.

5. Use exceptions as learning opportunities. They may reveal areas where the guidelines need to be updated or expanded.