ADR 003: API Documentation Standards
Status: Accepted | Date: 2025-03-26
Context
Secure, maintainable APIs require mature frameworks with low complexity and industry standard compliance. Where existing standards exist, prefer them over bespoke REST APIs.
Compliance Requirements:
Decision
API Requirements
| Requirement | Standard | Mandatory |
|---|---|---|
| Documentation | OpenAPI Specification | Yes |
| Testing | Restish CLI scripts | Yes |
| Framework | Huma or FastAPI | Recommended |
| Naming | Consistent convention | Yes |
| Security | OWASP API security coverage | Yes |
| Exposure | No admin APIs on Internet | Yes |
Development Guidelines
- Self-Documenting: Use frameworks that auto-generate OpenAPI specs
- Data Types: Prefer standard types over custom formats
- Segregation: Separate APIs by purpose
- Testing: Include security vulnerability checks in test scripts
API Development Flow:
Consequences
Without this approach: Security vulnerabilities, documentation drift, poor quality APIs, and increased maintenance overhead.
With this approach: Secure, well-documented APIs with automated testing and reduced maintenance burden.