API Design (REST + OpenAPI)
Deliver consistent APIs that frontend and integrations can consume confidently.
Recommended approach
- Use REST endpoints with explicit DTO contracts.
- Publish OpenAPI schema and generate typed clients.
- Version breaking changes explicitly.
Alternatives and when to choose them
- RPC-based contracts for tightly integrated internal platforms.
Implementation checklist
- Define naming and error-response conventions.
- Add OpenAPI generation workflow.
- Add deprecation policy for old endpoints.
Common pitfalls
- Leaking internal entities directly as public DTOs.
- Unversioned breaking changes.