Checklist

The checklist

Here’s everything we’ve covered, organized into a checklist you can use when versioning your own APIs.

Before versioning

• Understand what breaks clients (removing fields, renaming, type changes)
• Use additive changes whenever possible (new fields, new endpoints, optional params)
• Design responses for evolution (wrapped lists, structured errors, objects not primitives)

Versioning setup

• URL path versioning (/v1/, /v2/)
• Version prefix from day one (start with /v1/)
• Separate route files per version
• Shared queries and business logic
• Version-specific transformers that reshape shared rows per version
• Version-specific Zod schemas (different field names, validations)

Deprecation

• Deprecation: true header on deprecated versions
• Sunset header with the removal date
• Link header pointing to migration documentation
• Migration guide documenting all changes between versions
• Direct notification to known API consumers

Lifecycle

• Sunset policy documented (6 months, 12 months, etc.)
• Version usage tracked (total requests, per-client)
• 410 Gone response after sunset date
• Automated sunset enforcement in onRequest
• Usage monitoring before and after deprecation announcements

Field migration

• Four-step process: add, keep, deprecate, remove
• Both old and new field names during migration period
• Minimum 3 months for field-level migrations
• Minimum 6 months for version-level sunsets

Common mistakes

No versioning from the start. Starting with /books instead of /v1/books. Adding versioning later means either breaking the unversioned URL or maintaining two paths for the same version.

Copy-pasting route handlers. Copying the entire v1 folder into v2 and modifying it. Use shared queries with version-specific transformers instead. Copy-paste creates drift, and drift creates bugs.

Breaking changes without a new version. Renaming a field within v1 because “it’s just a small change.” It’s not small to the client that depends on it.

No deprecation period. Removing v1 overnight. Clients had no warning. Even 30 days is better than zero.

No usage monitoring. Sunsetting v1 when 20% of traffic still uses it. Check the data first.

Too many versions. v1, v2, v3, v4, v5. Each version has maintenance cost. Make each version last by using additive changes. Most APIs never need more than v2 or v3.