API Versioning

API Versioning Rules

1. Versioning Strategy Selection

Strategy Comparison

Decision Guide

• Default choice: URL path versioning — simplest, most widely understood
• When to use header versioning: Same resource, multiple representations; fine-grained version control needed; internal APIs
• When to use date-based: Frequent incremental changes; need account-level version pinning (like Stripe)
• When to use content negotiation: Strict REST/HATEOAS; limited use cases

Rules

• Expose only major version externally (e.g., /v1/, /v2/)
• Minor/patch versions are internal — transparent to clients
• Never run more than 2-3 major versions concurrently
• Set a sunset date when releasing a new major version

2. Breaking vs Compatible Changes

Breaking Changes (require new major version)

Grey Area (may be breaking depending on clients)

Backward Compatible Changes (safe without version bump)

• Add new endpoint
• Add optional request parameter
• Add field to response body (requires Tolerant Reader clients)
• Add new HTTP method to existing resource
• Relax validation rules
• Add optional header

3. Deprecation Policy

HTTP Headers (RFC 9745 + RFC 8594)

HTTP/1.1 200 OK
Deprecation: @1688169599
Sunset: Sun, 30 Jun 2024 23:59:59 GMT
Link: <https://api.example.com/v2/migration>; rel="successor-version"
Link: <https://api.example.com/deprecation-policy>; rel="deprecation"

• Sunset date MUST NOT be earlier than Deprecation date
• Past Deprecation date = already deprecated
• Future Deprecation date = advance notice

Deprecation Timeline

Deprecation Rules

• Never remove an API version without the full deprecation process
• Minimum deprecation period: 6 months for public APIs, 3 months for internal
• Monitor usage metrics before retirement — contact active consumers
• Provide machine-readable deprecation info (headers) alongside human-readable (docs)

4. API Lifecycle

Stage Transition Requirements

• Alpha → Beta: Design review complete, basic documentation
• Beta → GA: Compatibility policy defined, performance tested, SLA defined
• GA → Deprecated: Successor exists, migration guide provided, 6-12 month notice
• Deprecated → Retired: Usage below threshold, sunset date passed

5. API Evolution Patterns

Expand-and-Contract

Safely introduce breaking changes in three phases:

1. Expand: Add new field/endpoint alongside existing one (both work)
2. Migrate: Clients switch to new field/endpoint (monitor progress)
3. Contract: Remove old field/endpoint (after all clients migrated)

# Example: Split fullName into firstName + lastName

Phase 1 (Expand):
  { "fullName": "John Doe", "firstName": "John", "lastName": "Doe" }

Phase 2 (Migrate):
  Clients switch to firstName/lastName. Monitor fullName usage → 0.

Phase 3 (Contract):
  { "firstName": "John", "lastName": "Doe" }

Tolerant Reader

Client-side defensive design:

• Ignore unknown fields (never fail on extra data)
• Use defaults for missing fields
• Do not depend on field ordering
• Use lenient deserialization (e.g., @JsonIgnoreProperties(ignoreUnknown = true))

Additive-Only Strategy

• Add new features as new fields/endpoints only
• Never remove or modify existing fields
• Avoids major version bumps for extended periods
• Trade-off: API surface grows over time

6. Implementation Patterns

For detailed implementation examples, see references/implementation-patterns.md.

Spring Framework 7 / Spring Boot 4+

Note: Requires Spring Boot 4.0+ (Spring Framework 7). Not available in Boot 3.x.

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useRequestHeader("Api-Version");
    }
}

@RestController
@RequestMapping("/accounts")
public class AccountController {
    @GetMapping(path = "/{id}", version = "1")
    public AccountV1 getV1(@PathVariable Long id) { /* ... */ }

    @GetMapping(path = "/{id}", version = "2")
    public AccountV2 getV2(@PathVariable Long id) { /* ... */ }
}

Express.js

app.use("/api/v1", v1Router);
app.use("/api/v2", v2Router);

7. API Gateway Version Routing

Route versions at the gateway layer to decouple backend services.

Client → API Gateway → /v1/* → Backend v1 (port 8081)
                     → /v2/* → Backend v2 (port 8082)

Benefits

• Backend services don't need version routing logic
• Independent deployment and scaling per version
• Combine with canary deployment for gradual version transitions
• Centralized rate limiting and monitoring per version

Gateway-Specific Patterns

8. Common Anti-Patterns