be-api-versioning

Skill: REST API Versioning

Defines the versioning strategy for REST endpoints.

Why it matters: without versioning, any breaking change forces all clients to update at the same time. With versioning, the API can evolve while keeping compatibility with clients that have not migrated yet.

Recommended strategy — URL prefix

/api/v1/transactions       ← current version
/api/v2/transactions       ← new version (when there is a breaking change)
/api/transactions          ← temporary alias for /api/v1 during migration

Why URL instead of header: easier to test (curl, browser, logs), more explicit in documentation and bookmarks. Header versioning (Accept-Version: v2) is cleaner but less visible.

Centralize the prefix in one constant/config so controllers/routes never hand-type it.

When to create v2

Create a new version only for breaking changes:

Change	Breaking?	Action
Add optional field to response	❌	No new version needed
Add new endpoint	❌	No new version needed
Remove field from response	✅	New version required
Rename field	✅	New version required
Change field type	✅	New version required
Change behavior of an existing endpoint	✅	New version required

Version lifecycle

v1: Active       → used in production by everyone
v1: Deprecated   → announcement with sunset date (minimum 3 months)
v1: Sunset       → returns 410 Gone with migration link
v1: Removed      → endpoint deleted from the code

Deprecated endpoints must signal it in-band with standard headers:

Deprecation: true
Sunset: 2026-12-31                                  (RFC 8594)
Link: </api/v1/transactions>; rel="successor-version"

After sunset, return 410 Gone with a body pointing to the successor route.

Migration checklist (for unversioned projects)

Phase 1 — Add version (without breaking change):
□ Centralize the /api/v1 prefix constant
□ Add /api/v1/* to all routes
□ Keep /api/* as alias (no deprecation yet)
□ Update clients to use /api/v1/*
□ Commit and deploy

Phase 2 — Deprecate the unversioned route:
□ Add Deprecation + Sunset headers to /api/* endpoints
□ Announce the sunset date
□ Monitor logs to check whether legacy routes are still called

Phase 3 — Remove the legacy route:
□ Confirm in the logs that no client uses /api/*
□ Replace /api/* endpoints with 410 Gone
□ After the stabilization period: remove legacy code

Documentation

Publish one API-docs group per version (e.g., separate OpenAPI groups for /api/v1/** and /api/v2/**) so clients browse only the version they use.

Resources

• examples-spring.md — Spring Boot implementation: prefix constant, legacy-route coexistence, Deprecation/Sunset headers, 410 Gone responder, SpringDoc GroupedOpenApi per version.