[ADP-0] ADP Overview
This ADP is related to the design of the ADP Overview.
- ADP Number: 0000-0020 reserved for ADP-related ADPs.
What is ADP?
ADP stands for: API Design Principles; 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 ADP 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 ADP will theoretically continue to improve.
ADP 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 ADP design with specific actual products (although domain-related parts will involve the company's registered domain).
Therefore, the ADP 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 company's current situation.
Some content has not kept pace with the times.
Why is ADP 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 the company's trust and overall quality in software services, promoting the concept of API as a product.
- The ADP is designed to facilitate the sharing of URLs (for example, directly sending ADP-20 to API partners to reach a consensus on API contract design) to facilitate communication of API design concepts.
API lint for ADP
Currently, ADP 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 ADP?
Please refer to FAQ.
How to use ADP?
To effectively use ADP:
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 ADP list: Click the list link in the upper right corner to browse all available ADPs.
Explore by category: Use the left navigation bar to find ADPs grouped by topics such as "authentication," "version control," or "performance."
Apply to your work: When facing design decisions, refer to relevant ADPs. For example, if you are designing a new endpoint, check the ADPs related to URL structure and HTTP methods.
Remember, ADP is a guideline, not a strict rulebook. Use it to inform your decisions and improve your API design.
Contact ADP Designers
Currently, the overall maintenance of documents and tools for ADP is handled by Alive.Kuo.
References
The inspiration for this document comes from: