Module 8 - Networking and APIs

API Versioning

Evolve your API without breaking existing clients.

1The Restaurant Menu Analogy

Simple Analogy
A restaurant wants to add healthier options. They can't just change all dishes overnight-regulars expect their favorites. Instead, they keep old dishes while adding new ones, maybe marking old ones as "classic." API versioning is the same-support old and new simultaneously.

API versioning allows you to make breaking changes while maintaining backward compatibility for existing clients. It's the contract between your API and its consumers.

2Versioning Strategies

URL Path Versioning

/api/v1/users, /api/v2/users
Pros:
  • ✓ Explicit and visible
  • ✓ Easy to test in browser
  • ✓ Clear routing
Cons:
  • ✗ Not RESTful (resource URL changes)
  • ✗ Harder to deprecate

Used by: Stripe, Twilio, GitHub

Query Parameter

/api/users?version=2
Pros:
  • ✓ Optional (can default)
  • ✓ URL stays same
Cons:
  • ✗ Easy to miss
  • ✗ Caching complications
  • ✗ Less discoverable

Used by: Google, Amazon (some APIs)

Header Versioning

Accept: application/vnd.api+json;version=2
Pros:
  • ✓ Clean URLs
  • ✓ Truly RESTful
  • ✓ Flexible
Cons:
  • ✗ Hidden from URL
  • ✗ Harder to test
  • ✗ Requires header inspection

Used by: GitHub (Accept header)

Content Negotiation

Accept: application/vnd.company.v2+json
Pros:
  • ✓ Most RESTful
  • ✓ Fine-grained control
Cons:
  • ✗ Complex
  • ✗ Less intuitive

Used by: GitHub API

3When to Version

Breaking Changes (Need Version)
  • ✗Removing a field
  • ✗Renaming a field
  • ✗Changing data type
  • ✗Removing an endpoint
  • ✗Changing response structure
Non-Breaking (No Version Needed)
  • ✓Adding optional field
  • ✓Adding new endpoint
  • ✓Adding optional parameter
  • ✓Performance improvements
  • ✓Bug fixes

4Deprecation Strategy

1
Announce Deprecation
Blog post, changelog, API response headers. Give 6-12 months notice.
2
Add Sunset Header
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
3
Track Usage
Monitor who's still using old version. Reach out to major users.
4
Return Warnings
Add deprecation warnings in response body/headers.
5
End of Life
Return 410 Gone or 301 redirect to new version.

5Real-World Example: Stripe

Stripe's Approach
// Request with specific version
curl https://api.stripe.com/v1/charges \
  -H "Stripe-Version: 2023-10-16"

// Response includes version info
{
  "api_version": "2023-10-16",
  "data": {...}
}

// Default: your account's pinned version
// Override per-request with header

Stripe pins each account to a version at signup. You upgrade when ready. Breaking changes are opt-in.

6Best Practices

Use Semantic Versioning for Major Changes

v1, v2, v3 for breaking changes. Not v1.1, v1.2 for API versions.

Support At Least 2 Versions

Current and previous. Give clients time to migrate.

Document Changes Clearly

Changelog with breaking vs non-breaking changes. Migration guides.

Version from Day One

Start with /v1/. Adding versioning later is painful.

Default to Latest (Carefully)

Or pin to specific version. Stripe pins at signup, GitHub defaults to latest.

7Key Takeaways

1URL path versioning (/v1/) is most common and explicit
2Only version for breaking changes. Adding fields is safe.
3Deprecation: announce early, track usage, sunset gracefully
4Support at least 2 versions simultaneously
5Start with /v1/ from day one. Adding later is painful.

?Quiz

1. Adding a new optional field to response. Do you need new version?

2. Which versioning is most explicit and testable?