Implementing Service Versioning
1. Understanding Semantic Versioning
| MAJOR.MINOR.PATCH | When |
|---|---|
| MAJOR | Breaking change |
| MINOR | Backward-compatible feature |
| PATCH | Backward-compatible fix |
| Pre-release | 1.2.0-rc.1 |
| Build metadata | 1.2.0+sha.abc123 |
2. Implementing API Versioning Strategies
| Strategy | Example | Pros / Cons |
|---|---|---|
| URI path | /v1/orders | Visible, simple / URL churn |
| Header | API-Version: 2 | Clean URLs / hidden, harder to test |
| Accept media type | application/vnd.acme.v2+json | RESTful purist / verbose |
| Query param | ?v=2 | Cache-unfriendly |
3. Implementing Schema Versioning
| Tech | Mechanism |
|---|---|
| Protobuf | Field numbers immutable; new = optional |
| Avro | Reader/writer schema, default values |
| JSON Schema | $id + $version field |
| Schema Registry | Confluent SR, Apicurio — compat checks |
4. Implementing Protocol Versioning
| Mechanism | Detail |
|---|---|
| Handshake | Client sends supported versions |
| Server selects max common | Negotiated |
| Examples | TLS, HTTP/2 ALPN, Kafka API versions |
5. Handling Breaking Changes
| Type | Strategy |
|---|---|
| Field removed | Deprecate first, ship MAJOR |
| Type change | Add new field, dual-write/dual-read |
| Behavior change | Feature flag + new endpoint |
| Expand-then-contract | Add new → migrate clients → remove old |
6. Implementing Deprecation Policies
| Stage | Detail |
|---|---|
| Announce | Docs + Deprecation + Sunset headers (RFC 8594/9745) |
| Window | ≥ 6-12 months for public APIs |
| Track usage | Per-client metrics → outreach |
| Final removal | 410 Gone with migration link |
7. Understanding Version Compatibility Matrix
| Direction | Definition |
|---|---|
| Backward compat | New code reads old data |
| Forward compat | Old code reads new data (ignore unknown fields) |
| Full compat | Both |
| Wire compat | Old clients ↔ new servers and vice versa |
8. Implementing Version Negotiation
| Pattern | Detail |
|---|---|
| Server-driven | Server picks best supported |
| Client-driven | Client requests specific version |
| Default | Latest stable if unspecified |
9. Implementing Multi-Version Support
| Tactic | Detail |
|---|---|
| Side-by-side handlers | One controller per version |
| Adapter / facade | Translate v1 ↔ v2 on entry |
| Common core | Shared domain logic |
| Limit number | Avoid > 2-3 active versions |
10. Understanding Sunset Strategies
| Step | Detail |
|---|---|
| Headers | Deprecation: true, Sunset: <date> |
| Brownouts | Periodic intentional 410s before final |
| Rate-limit old version | Encourage migration |
| Final | Remove + redirect docs |