MEDIUMArchitecturelargeAPI Design

Version Your API

Version your API from day one (URL prefix, header, or query param). Without versioning, any breaking change forces all clients to update simultaneously or breaks them without warning.

Why This Matters

Without API versioning, every change is either backward-compatible or a breaking change that affects all consumers simultaneously. Adding a required field breaks old clients. Removing a field breaks clients that depend on it. Renaming a field breaks everyone. Versioning lets you evolve the API while giving consumers time to migrate, preventing the "deploy and pray" pattern that causes widespread outages.

Related Rules

Validate All Request Input

Security

CRITICAL

Use Proper HTTP Status Codes

Quality

MEDIUM

Implement Rate Limiting

Security

HIGH

Catch this automatically on every PR

BeforeMerge scans your pull requests against this rule and 3+ others. Get actionable feedback before code ships.

Join Waitlist Browse All Rules

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:

URL prefix (recommended): /api/v1/users, /api/v2/users
Header: Accept: application/vnd.myapp.v2+json
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

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