ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-20] Engineering Principles ​

reviewing phase 1

This article needs more references and practical content.

API First is one of our core engineering principles. This document outlines API First and several related or worth-mentioning engineering principles.

Principle List ​

API First ​

API First is a development approach that prioritizes the design and development of APIs before implementing the underlying systems. Key aspects include:

  • Designing APIs before writing any code
  • Using API description formats like OpenAPI (Swagger)
  • Ensuring consistency across all APIs
  • Facilitating parallel development of front-end and back-end systems
  • Using API testing and validation

See ADP-22 for more details.

DevOps and Continuous Integration/Continuous Deployment (CI/CD) ​

DevOps practices and CI/CD pipelines support API First by:

  • Automating API testing and validation
  • Enabling rapid iteration and deployment of API changes
  • Facilitating consistent environments across development, testing, and production

Documentation as Code ​

Treating documentation as code aligns well with API First:

  • Maintaining API documentation alongside code
  • Automatically generating and updating documentation from API specifications
  • Ensuring documentation stays current with API changes

Security by Design ​

Integrating security into the API design process:

  • Implementing proper authentication and authorization mechanisms
  • Ensuring data privacy and protection
  • Conducting regular security audits of APIs

Versioning and Backward Compatibility ​

See ADP-24 for more details.

Developer Experience (DX) ​

See ADP-23 for more details.

Adopt Best Practices ​

See ADP-21 for more details.

Guidance ​

  • Teams SHOULD properly incorporate these principles into their development workflows, ensuring that API design and development are prioritized throughout the software development lifecycle.
  • These principles SHOULD be regularly reviewed and updated to reflect evolving best practices, technologies, and team experiences. Feedback and suggestions for improvements are encouraged from all team members.