API Versioning Strategies: URI vs Header vs Query

Changing API contracts without versioning breaks existing clients. Versioning too aggressively fragments the API surface and increases maintenance burden.

Choose the right versioning strategy for your context.

// Strategy 1: URI versioning (most common, most visible)
GET /v1/users
GET /v2/users

// Strategy 2: Header versioning (clean URLs, harder to test)
GET /users
Accept: application/vnd.myapi.v2+json

// Strategy 3: Query parameter (simple, but not RESTful)
GET /users?version=2

// Strategy 4: Content negotiation with date (Stripe style)
Stripe-Version: 2023-10-16

// Express URI versioning example
const v1 = express.Router();
const v2 = express.Router();

v1.get('/users', v1UsersHandler);
v2.get('/users', v2UsersHandler);

app.use('/v1', v1);
app.use('/v2', v2);

URI versioning is explicit and easily testable. Header versioning is cleaner but requires API clients to set custom headers. Date-based versioning (Stripe's approach) versions the server not the endpoints.