Stage 3 · Build
API Design & gRPC
REST Versioning
Choose URI, header, or media type versioning and plan deprecations without breaking clients.
Why Version APIs
APIs evolve. Clients cannot always update immediately. Without versioning, a breaking change forces every client to update at the same time. Versioning lets you deploy changes while supporting existing clients.
URI Versioning
The most common approach. The version is embedded in the URL path. Simple, explicit, and easy to route. The downside is URL proliferation.
Header Versioning
Media Type Versioning
Deprecation Strategy
Plan deprecation before launching. When you need to break compatibility, follow a predictable cycle: announce, support both versions, sunset the old one.
| Approach | Pros | Cons |
|---|---|---|
| URI (/api/v1) | Simple, explicit, cacheable | URL proliferation |
| Header (X-API-Version) | Clean URLs | Hard to test, invisible |
| Media Type | Standards-based | Complex, tooling support |
Breaking Changes
- Removing a field from the response
- Renaming a field
- Changing a field type (string to int)
- Changing URL structure
- Removing an endpoint
- Changing authentication requirements
- Adding required request fields
Adding new fields, new endpoints, and new optional request parameters are all additive changes. They do not break existing clients. Make additive changes without bumping the version.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.