Frequently Asked Questions

General Questions

What happens if I violate some ADP guidelines?

You will not be penalized. The role of ADP is to assist rather than to act as a lawyer. However, it is recommended to follow these guidelines to ensure consistency and best practices across the organization.

How often does ADP get updated?

ADP is regularly reviewed and updated as needed. The frequency of updates may vary based on specific ADPs and changes in industry standards or organizational needs.

Can I propose a new ADP?

Yes, you can propose a new ADP. Please follow the guidelines outlined in ADP-2: Writing ADP to submit a new ADP proposal.

Writing and Structure of ADP

What language should I use when writing an ADP?

ADPs should be written in American English to maintain consistency throughout the document. However, if resources allow, Traditional Chinese translations may be provided.

How should I format my ADP?

ADPs should be written in Markdown format. For detailed formatting guidelines, please refer to ADP-2.

How are ADPs categorized?

ADPs are categorized into predefined categories such as "ADP itself," "Engineering Principles," "HTTP Basics," etc. For a complete list of categories, please refer to ADP-2.

How are ADP numbers assigned?

ADP numbers are assigned based on the specific scope of different types of APIs. For more information on ADP numbering, please refer to ADP-3.

API Design and Implementation

Do I need to include OpenAPI examples in my ADP?

Yes, if your ADP is related to HTTP API design, you should include OpenAPI documentation examples as required by ADP-2.

What if my specific API needs to deviate from ADP guidelines?

If you need to deviate from the guidelines, you can specify exceptions as outlined in ADP-46. Be sure to document the reasons for the deviation and any potential impacts.

How do I register new API-related terms or concepts?

Follow the API terminology registration process described in ADP-49 to register new issue types, custom preferences, application IDs, custom headers, link relations, or authorization schemes.

Version Control and Changes

How are changes handled in ADP?

ADP follows the lifecycle outlined in ADP-2. If significant changes occur that render the ADP itself inapplicable, it needs to be deprecated.

What should I do if I find errors or have suggestions for existing ADPs?

If you find errors or have suggestions, you can submit feedback or propose changes through the repository on the ADP website. Submit a pull request following the guidelines mentioned in ADP-2.

Compliance and Governance

Who is responsible for overseeing the ADP process?

Tentatively, it is the designer of the website; please see ADP-1.

How often are exceptions to ADP reviewed?

Exceptions should be reviewed regularly to ensure they are still necessary and do not negatively impact the overall API ecosystem. The exact frequency may vary, but it is best to review at least once a year.

Where can I find the internal page with all registered API terms and concepts?

The organization maintains an internal site with all registered terms, issue types, preferences, and application IDs. Please contact the ADP designer (refer to ADP-1) for access to this repository/page.

Currently, this internal site is still in planning.