[ADE-0] ADE Overview
This ADE is related to the design of the ADE Overview.
- ADE Number: 0000-0020 reserved for ADE-related ADEs.
What is ADE?
ADE stands for: API Design Essentials; a comprehensive collection of API design conventions, guidelines, best practices, and improvement proposals. The main purpose is to standardize API design, ensuring consistency of APIs both within the organization and between different organizations. For more design concepts, please refer to ADE Purpose.
When designing APIs, developers often face many decision-making scenarios. Sometimes we need to find a balance between practice and theory, and more often we need clear references to determine "how something should be done."
Some design specifications already have RFC standards to follow, but some may still be in draft form. We will strive to research any specifications or conventions related to API design and provide clear guidelines as references.
Generally, all directions involved in API design have more than one existing solution, but there may still be shortcomings. The ADE will theoretically continue to improve.
ADE currently uses markdown files for writing and is maintained on GitHub. The document display interface uses vitepress.
Why create this site?
The inspiration for this site mainly comes from the API specifications of Zalando and OTTO, as well as Google's AIP website. (See the references section of this document.)
According to these sites, the designers did not tightly couple the ADE design with specific actual products (although domain-related parts will involve the registered domain).
Therefore, the ADE can serve as a reference for any API designer when designing APIs, similar to what is mentioned in Google AIP.
Why not directly use the content of Zalando/OTTO/Google AIP as design specifications?
Some content is not applicable to the current situation.
Some content has not kept pace with the times.
Why is ADE a public site rather than Confluence pages?
- API design itself should not be related to sensitive or business logic; it is more like a common language between the front end and back end. The purpose of language is communication, and communication should not be conducted in secrecy.
- The designers of this site believe that public API design specifications can enhance trust and overall quality in software services, promoting the concept of API as a product.
- The ADE is designed to facilitate the sharing of URLs (for example, directly sending ADE-20 to API partners to reach a consensus on API contract design) to facilitate communication of API design concepts.
API lint for ADE
Currently, ADE uses redocly as the API lint tool and has customized a set of rules for some programmable rules. For installation and usage, please refer to API Lint.
What happens if I do not follow ADE?
Please refer to FAQ.
How to use ADE?
To effectively use ADE:
Use the top search box: Enter keywords related to your current design issues. For example, if you are designing error responses, search for "error handling" or "status codes."
Browse the complete ADE list: Click the list link in the upper right corner to browse all available ADEs.
Explore by category: Use the left navigation bar to find ADEs grouped by topics such as "authentication," "version control," or "performance."
Apply to your work: When facing design decisions, refer to relevant ADEs. For example, if you are designing a new endpoint, check the ADEs related to URL structure and HTTP methods.
Remember, ADE is a guideline, not a strict rulebook. Use it to inform your decisions and improve your API design.
Maintainer
Alive Kuo -- alegnadise@gmail.com
References
The inspiration for this document comes from: