Version Your API

Why this matters

APIs are contracts. Once a client integrates with your API, they depend on the exact shape of requests and responses. Without versioning, you face a painful choice with every change:

• Make it backward-compatible: accumulate debt by never removing deprecated fields, never renaming anything, never changing response shapes. The API becomes a museum of every past decision.
• Make a breaking change: break every client simultaneously. Mobile apps in the App Store can't update instantly. Third-party integrations break without warning. Partners lose trust.

Versioning solves this by letting you run old and new versions in parallel. Clients migrate on their own schedule. You deprecate old versions with advance notice. Breaking changes are contained to new versions.

The rule

Version your API from the first release. The three common strategies:

1. URL prefix (recommended): /api/v1/users, /api/v2/users
2. Header: Accept: application/vnd.myapp.v2+json
3. Query parameter: /api/users?version=2

URL prefix is the simplest, most visible, and easiest to route. Use it unless you have a specific reason not to.

Bad example

// BAD: no versioning — /api/users
// Changing the response shape breaks all clients
export async function GET() {
  const users = await db.user.findMany();
 
  return Response.json(
    // If you need to change this shape, every client breaks
    users.map((u) => ({
      id: u.id,
      name: u.name,
      email: u.email,
    }))
  );
}

Good example

app/
  api/
    v1/
      users/
        route.ts    # Original shape
    v2/
      users/
        route.ts    # New shape — old clients unaffected

// app/api/v1/users/route.ts — original format
export async function GET() {
  const users = await db.user.findMany();
  return Response.json(
    users.map((u) => ({ id: u.id, name: u.name, email: u.email }))
  );
}
 
// app/api/v2/users/route.ts — new format with breaking changes
export async function GET() {
  const users = await db.user.findMany({
    include: { profile: true },
  });
  return Response.json(
    users.map((u) => ({
      id: u.id,
      displayName: `${u.profile.firstName} ${u.profile.lastName}`,
      contactEmail: u.email,
      avatarUrl: u.profile.avatarUrl,
    }))
  );
}

How to detect

Check if API routes include a version prefix:

ls app/api/

If routes are directly under app/api/ without a v1/ or version prefix, the API is unversioned.

Remediation

1. Add a version prefix to all existing routes: move app/api/users/ to app/api/v1/users/
2. Set up a redirect from the old unversioned path to v1 for backward compatibility
3. Document the versioning strategy in your API docs
4. When making breaking changes, create a new version directory and keep the old one running
5. Set a deprecation policy: "v(N-2) is deprecated and will be removed 6 months after v(N) launch"

References

• REST API Versioning: Strategies and Best Practices
• Stripe API Versioning
• Microsoft REST API Guidelines: Versioning