[ADP-21] Best Practices

reviewing phase 1

This article needs more reference and practical content.

Design Thinking

Even with established initial and evolving principles, there may be aspects we haven't covered. This could be due to new standards emerging after our principles were set, or unforeseen requirements.

For instance, OpenAPI doesn't describe how to handle asynchronous requests, which is where AsyncAPI comes in. Additionally, if we decide to support both REST and GraphQL in the future, despite GraphQL lacking a universal standard, we can still identify best practices through collective brainstorming, drawing from RFCs or available online resources. Before creating new solutions, it's crucial to determine if existing industry standards or common practices can address your problem or meet your needs.

Beyond API design, implementation details are equally important. Before deciding to write new libraries for standards, search for relevant packages, libraries, and discussions, and evaluate whether these solutions fit your product or application.

Guidance

• You SHOULD research industry standards or common practices for best practices.
• If you believe existing standards don't meet your requirements, you SHOULD design and request internal feedback (RFC), aiming to develop it into a best practice.
• You SHOULD document your internal RFCs.
• You SHOULD regularly review and update best practices to ensure they remain aligned with industry trends and organizational needs.