Content Role: pillar

Semantic Versioning: API Evolution Strategy

Breaking changes and backwards compatibility in REST and GraphQL

API evolution presents a fundamental challenge: how do you improve your API without breaking existing integrations? Every modification—from adding new fields to changing response structures—carries the risk of disrupting downstream consumers. The cost of breaking changes extends beyond immediate technical debt; it erodes trust, fragments your user base across incompatible versions, and creates maintenance nightmares.

Semantic versioning provides a structured framework for communicating the nature and impact of API changes. When applied correctly to APIs, it transforms version numbers from arbitrary labels into meaningful contracts that signal compatibility guarantees to consumers.

Understanding Semantic Versioning for APIs

Semantic versioning (SemVer) uses a three-part version number: MAJOR.MINOR.PATCH (e.g., 2.4.1). Each component carries specific meaning:

• MAJOR: Incremented for incompatible API changes that break existing consumers
• MINOR: Incremented for backwards-compatible functionality additions
• PATCH: Incremented for backwards-compatible bug fixes

For APIs, this translates to clear expectations. A consumer using version 2.3.0 knows they can safely upgrade to 2.3.5 or 2.4.0 without code changes, but upgrading to 3.0.0 requires reviewing breaking changes and potentially modifying their integration.

Defining Breaking Changes

Not all changes are created equal. Understanding what constitutes a breaking change is critical for proper version management.

Definite breaking changes:

• Removing endpoints or fields
• Renaming fields or parameters
• Changing field data types
• Adding required parameters
• Modifying error response structures
• Changing authentication mechanisms
• Altering rate limiting behavior significantly

Non-breaking changes:

• Adding new endpoints
• Adding optional parameters
• Adding new fields to responses
• Deprecating (but not removing) features
• Performance improvements
• Bug fixes that restore documented behavior

The gray area involves changes that technically maintain backwards compatibility but alter behavior in ways consumers might depend on—like changing default values or modifying validation rules.

REST API Versioning Strategies

URL Path Versioning

The most explicit approach embeds the version in the URL path:

// Express.js example with TypeScript
import express, { Request, Response } from 'express';

const app = express();

// Version 1 - Original implementation
app.get('/api/v1/users/:id', async (req: Request, res: Response) => {
  const user = await getUserById(req.params.id);
  res.json({
    id: user.id,
    name: user.name,
    email: user.email
  });
});

// Version 2 - Breaking change: restructured response
app.get('/api/v2/users/:id', async (req: Request, res: Response) => {
  const user = await getUserById(req.params.id);
  res.json({
    id: user.id,
    profile: {
      fullName: user.name,
      contactEmail: user.email
    },
    metadata: {
      createdAt: user.createdAt,
      lastModified: user.updatedAt
    }
  });
});

Advantages: Clear, cacheable, easy to route Disadvantages: URL proliferation, requires maintaining multiple codebases

Header-Based Versioning

Version information travels in HTTP headers:

import express, { Request, Response, NextFunction } from 'express';

interface VersionedRequest extends Request {
  apiVersion: string;
}

// Middleware to extract version
const versionMiddleware = (req: VersionedRequest, res: Response, next: NextFunction) => {
  const version = req.headers['api-version'] || '1.0.0';
  req.apiVersion = version;
  next();
};

app.use(versionMiddleware);

app.get('/api/users/:id', async (req: VersionedRequest, res: Response) => {
  const user = await getUserById(req.params.id);

  if (req.apiVersion.startsWith('1.')) {
    return res.json(transformToV1Format(user));
  }

  if (req.apiVersion.startsWith('2.')) {
    return res.json(transformToV2Format(user));
  }

  res.status(400).json({ error: 'Unsupported API version' });
});

Advantages: Clean URLs, flexible Disadvantages: Less discoverable, caching complexity

Content Negotiation

Using Accept headers for version specification:

app.get('/api/users/:id', async (req: Request, res: Response) => {
  const acceptHeader = req.headers.accept || '';

  if (acceptHeader.includes('application/vnd.myapi.v2+json')) {
    const user = await getUserById(req.params.id);
    return res.json(transformToV2Format(user));
  }

  // Default to v1
  const user = await getUserById(req.params.id);
  res.json(transformToV1Format(user));
});

GraphQL Versioning Approach

GraphQL's philosophy differs fundamentally from REST. The GraphQL specification recommends avoiding versioning through continuous evolution:

import { GraphQLObjectType, GraphQLString, GraphQLSchema } from 'graphql';

const UserType = new GraphQLObjectType({
  name: 'User',
  fields: () => ({
    id: { type: GraphQLString },
    name: { type: GraphQLString },
    email: { type: GraphQLString },

    // Deprecated field - kept for backwards compatibility
    fullName: {
      type: GraphQLString,
      deprecationReason: 'Use `name` instead. Will be removed in 2025-Q2.',
      resolve: (user) => user.name
    },

    // New field added without breaking changes
    profile: {
      type: ProfileType,
      resolve: (user) => ({
        displayName: user.name,
        contactEmail: user.email
      })
    }
  })
});

GraphQL's introspection allows clients to query available fields and their deprecation status:

// Client can detect deprecated fields
const query = `
  query {
    __type(name: "User") {
      fields(includeDeprecated: true) {
        name
        isDeprecated
        deprecationReason
      }
    }
  }
`;

When breaking changes are unavoidable in GraphQL, use schema namespacing:

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      // Current API
      user: {
        type: UserType,
        args: { id: { type: GraphQLString } },
        resolve: (_, { id }) => getUserById(id)
      },

      // Experimental/next version
      v2: {
        type: V2QueryType,
        resolve: () => ({}) // Namespace for v2 queries
      }
    }
  })
});

Implementing Version Deprecation

Proper deprecation requires communication and grace periods:

interface DeprecationInfo {
  version: string;
  deprecatedAt: Date;
  sunsetDate: Date;
  migrationGuide: string;
}

const deprecationMiddleware = (deprecationInfo: DeprecationInfo) => {
  return (req: Request, res: Response, next: NextFunction) => {
    const daysUntilSunset = Math.floor(
      (deprecationInfo.sunsetDate.getTime() - Date.now()) / (1000 * 60 * 60 * 24)
    );

    res.setHeader('X-API-Deprecation', 'true');
    res.setHeader('X-API-Sunset-Date', deprecationInfo.sunsetDate.toISOString());
    res.setHeader('X-API-Migration-Guide', deprecationInfo.migrationGuide);

    if (daysUntilSunset < 30) {
      res.setHeader('X-API-Deprecation-Warning', 
        `This version will be sunset in ${daysUntilSunset} days`);
    }

    next();
  };
};

app.use('/api/v1/*', deprecationMiddleware({
  version: '1.0.0',
  deprecatedAt: new Date('2024-01-01'),
  sunsetDate: new Date('2024-12-31'),
  migrationGuide: 'https://docs.api.example.com/migration/v1-to-v2'
}));

Common Pitfalls

Versioning too aggressively: Creating a new major version for every change fragments your user base. Reserve major versions for truly breaking changes.

Insufficient testing across versions: Each supported version requires comprehensive test coverage. Implement version-specific test suites:

describe('User API', () => {
  describe('v1', () => {
    it('returns flat user structure', async () => {
      const response = await request(app)
        .get('/api/v1/users/123')
        .expect(200);

      expect(response.body).toHaveProperty('name');
      expect(response.body).not.toHaveProperty('profile');
    });
  });

  describe('v2', () => {
    it('returns nested user structure', async () => {
      const response = await request(app)
        .get('/api/v2/users/123')
        .expect(200);

      expect(response.body).toHaveProperty('profile.fullName');
    });
  });
});

Unclear deprecation timelines: Consumers need predictable sunset schedules. Establish and communicate a clear deprecation policy (e.g., "Major versions supported for 18 months after successor release").

Ignoring monitoring: Track version usage to inform deprecation decisions:

const versionMetrics = (req: VersionedRequest, res: Response, next: NextFunction) => {
  const version = req.apiVersion;
  metrics.increment('api.requests', { version, endpoint: req.path });
  next();
};

Breaking semantic versioning rules: Introducing breaking changes in minor versions destroys trust. When in doubt, increment the major version.

Best Practices Checklist

• [ ] Document your versioning strategy in API documentation
• [ ] Use semantic versioning consistently across all APIs
• [ ] Implement automated tests for each supported version
• [ ] Set up monitoring to track version adoption
• [ ] Establish a deprecation policy with clear timelines
• [ ] Communicate breaking changes at least 6 months before implementation
• [ ] Provide migration guides with code examples
• [ ] Use deprecation headers in responses
• [ ] Maintain a public changelog following Keep a Changelog format
• [ ] Version your API documentation alongside code
• [ ] Consider backwards compatibility before every change
• [ ] Implement feature flags for gradual rollouts
• [ ] Set up alerts for deprecated version usage spikes

FAQ

Q: Should I version from v1 or v0? Starting with v0 signals pre-release status where breaking changes are expected. Use v0 during initial development, then move to v1 when the API is production-ready and you're committing to stability.

Q: How many versions should I support simultaneously? Support N and N-1 major versions at minimum. This gives consumers time to migrate while limiting maintenance burden. High-traffic APIs might support N, N-1, and N-2.

Q: Can I fix bugs in old versions without incrementing the version? Yes, bug fixes that restore documented behavior are patch-level changes. However, if consumers depend on the buggy behavior, communicate the fix as you would a breaking change.

Q: How do I handle versioning in microservices? Each service should version independently based on its own evolution. Use a service mesh or API gateway to route requests to appropriate service versions. Document inter-service version compatibility in a dependency matrix.

Q: Should GraphQL APIs use semantic versioning? GraphQL schemas benefit from semantic versioning for the overall API contract, even while using field-level deprecation. Version the schema itself (e.g., schema v2.1.0) to track significant changes.

Q: What's the best way to version webhooks? Include version information in webhook payloads and allow consumers to specify their preferred version during webhook registration. Maintain backwards compatibility by including both old and new field formats during transition periods.

Q: How do I version authentication mechanisms? Treat authentication changes as major version bumps. Support multiple authentication methods simultaneously by detecting the auth type from headers or tokens, allowing gradual migration.