ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

ADP Site: BETA & RFC ​

v1.0.0 Release Target: August 31, 2024 ​

This site is currently under construction. Several ADPs are pending review and refinement.

Some articles are marked as PLACEHOLDER or DRAFT.

RFC Contact: alive.kuo@vivotek.com

To-Do List ​

API Documentation Versioning ​

  • Implement version control for API documentation to align with API versioning.
  • Clearly indicate the corresponding API version for each documentation set.
  • Consider using tools that support documentation versioning alongside code versioning.

Multilingual API Documentation ​

  • Provide guidelines for creating and maintaining multilingual API documentation.
  • Prioritize languages based on target audience and business needs.
  • Ensure consistency across different language versions of the documentation.

API Change Notification Mechanism ​

  • Establish a formal process for notifying API consumers about significant changes.
  • Categorize changes (e.g., breaking, non-breaking, deprecation) and communicate them accordingly.
  • Utilize multiple channels (e.g., email, developer portal, API responses) for change notifications.

API Performance Benchmarks ​

  • Define performance benchmarks for different types of API operations.
  • Include metrics such as response time, throughput, and error rates.
  • Regularly review and update benchmarks based on system improvements and user expectations.

API Mocking and Sandbox Environments ​

  • Provide mocking or sandbox environments for developers to test APIs.
  • Offer different levels of sandbox environments (e.g., stateless, stateful) based on testing needs.
  • Ensure sandbox environments closely mimic production behavior while protecting sensitive data.

API Security Scanning ​

  • Implement regular security scanning for all APIs.
  • Define the frequency of security scans based on the criticality of the API.
  • Use automated tools for continuous security monitoring alongside periodic manual audits.

Cross-functional Team Collaboration ​

  • Establish guidelines for collaboration between different teams in the API design process.
  • Use collaborative tools that facilitate input from various stakeholders.
  • Define clear roles and responsibilities for each team involved in the API lifecycle.