Our REST API serves three mobile applications, two web clients, and partner systems. Each client has a different deployment cycle. We need versioning.
Three Strategies¶
URL path: /api/v1/projects — the most readable, easy to route.
Header: Accept: application/vnd.core.v2+json — cleaner, but harder to test.
Query param: ?version=2 — a compromise.
We chose URL path versioning — simplicity wins.
Breaking vs. Non-Breaking Changes¶
- Breaking: Removing/renaming a field, changing a type → new version
- Non-breaking: Adding a field, new endpoint, optional parameter → same version
The key principle: stay additive-only for as long as possible. Deprecation process: Sunset header, notify clients, 6 months of monitoring, then shut down.
Version from Day One¶
Adding versioning retroactively is harder. Even with a single client, start with /api/v1/.
restapiverzováníarchitektura
Need help with implementation?
Our experts can help with design, implementation, and operations. From architecture to production.
Contact us