ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-2] ADP Writing ​

Guidance ​

  • ADP designs SHOULD be product-agnostic; these principles are intended to apply to every product, project, or application within different business units of the same company.

    • Exception: We have reserved some ADP numbers for specific products, see ADP Numbers.

  • Each ADP MAY contain one or more guidelines or design recommendations.

  • If the guideline requires more than one sentence to describe, it SHOULD become a new ADP page.

  • Each ADP MUST use uppercase MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, or MAY NOT, following the RFC 2119 requirement keywords.

  • Each ADP SHOULD be categorized into a specific existing ADP category unless there is a need to create a new category.

  • Each ADP SHOULD include examples where applicable to illustrate key concepts and provide practical use cases.

  • Each ADP SHOULD be written in American English to maintain document consistency.

    • If resources allow, each ADP MAY have a Traditional Chinese version to accommodate non-English readers.

  • Each ADP SHOULD use Markdown format for ease of editing, reading, and compatibility with various tools.

  • The markdown frontmatter area of each ADP document SHOULD record a unique ID and other necessary information. This ID is used for web routing and communication among developers.

    markdown
    ---
id: 1
title: Treat Developer Experience as important as User Experience
state: draft
created: 2024-12-12 # ISO8601 date of creation date
updated: 2024-12-13 # ISO8601 date of last modified date
---

# Treat Developer Experience as important as User Experience

## Overview
...

  • Each ADP SHOULD NOT use H1 headings (#), as the title already occupies the H1 level.

  • Each ADP SHOULD clearly specify its category from a predefined list to ensure proper organization and easy navigation.

  • Once an ADP transitions from draft to published status, a CHANGELOG field SHOULD be appended.

  • Each ADP MAY link to other ADPs using markdown link syntax, targeting ADPs by their id:

    md
      - See [ADP describing this topic](11)

  • Each ADP MUST pass the internal markdownlint check within the repo

    sh
    pnpm run docs:lint
    sh
    docs:lint /Users/alive/Projects/api-design-principle-beta
> markdownlint-cli2 "**/*.md" "#node_modules"

markdownlint-cli2 v0.13.0 (markdownlint v0.34.0)
Finding: **/*.md !node_modules
Linting: 334 file(s)
Summary: 43 error(s)

  • SHOULD use common terms defined in the Glossary.

HTTP API ADP ​

  • Each ADP related to HTTP API design SHOULD include examples of OpenAPI documentation, as OpenAPI is our chosen tool for HTTP API documentation.

ADP Lifecycle ​

  • Each ADP SHOULD mark its lifecycle stage in the markdown frontmatter area, with the following stages:
    • state: draft From the submission of a pull request to its inclusion in the repo, it is in draft status. Draft status is not only present during pull requests; sometimes we need to pre-release an ADP draft as a preview and basis for subsequent discussions.
    • state: reviewing After being included in the repo, it enters review status until a specific ADP reviewer starts the review. The review process may go through multiple phases, additionally marked with phase: ${number} in the frontmatter area.
    • state: published After the review ends, it enters published status. Once in published status, any changes require adding a changelog at the end of the ADP.
    • state: deprecated If an ADP is deemed no longer applicable, it enters deprecated status.

ADP Categories ​

Currently, we divide ADPs into the following categories:

  • ADP Itself: Documentation and guidelines related to the ADP framework and its components.
  • Engineering Principles: Core engineering principles and best practices guiding the development process.
  • HTTP Basics: Basic concepts of HTTP, including methods, status codes, and headers.
  • REST Basics: Principles and practices for designing RESTful APIs, including resource modeling and URI design.
  • HTTP Semantics: Detailed explanations of HTTP semantics and their application in API design and implementation.
  • JSON Principles: Guidelines for structuring JSON data, including naming conventions and data types.
  • Error Design: Best practices for designing and handling errors in APIs, including error codes and response formats.
  • Event Design: Principles for designing event-driven architectures, including event types and payload structures.
  • Naming Conventions: Standardized naming conventions for various elements in APIs, such as resources, parameters, and fields.
  • Application-Specific Conventions: Custom guidelines and conventions specific to application domains or project requirements.

These categories may change and reorganize as we continuously improve and expand the documentation framework.

Proposing a New ADP ​

  • MUST use markdown format.
  • Submit a pull request in the ADP site's repository. (Note: It may be a mirror repository. Find the upstream repository).
  • The proposal MUST include:
    1. Composite frontmatter content, including the ADP number.
    2. Clear title and article.
    3. Explicit principles using RFC Requirement Keywords.
    4. Design rationale if necessary.
    5. Design reference links.
  • [Draft] The review process is TBD now.
  • Feedback and revisions may be requested before acceptance.

Writing an ADP ​

  • Identify the specific topic you want to elaborate on.
  • Start researching whether standards (IEEE RFC, W3) already have solutions or proposals for this topic.
  • If there are no standards, there must be conventions to follow; try to evaluate better options among various solutions.
  • If no conventions are found, consider designing the content from scratch.

References ​