Guides ยท Engineering
API Schema Versioning Basics
Version schemas safely
This guide explains how to version API schemas: backward compatibility, additive changes, deprecation notices, separate versions or namespaces, and clear schema docs.
- api schema
- versioning
- compatibility
- deprecation
- namespaces
Prefer additive changes
Add fields instead of removing; make breaking changes rare and planned.
Version clearly
Use versioned namespaces or endpoints; document differences.
Deprecate carefully
Announce timelines and support overlap; provide migration guidance.
Test both versions
Validate old and new schemas in CI to prevent regressions.