API Versioning 2026

API versioning lets you evolve your interfaces without breaking existing users and clients.

Overview

API versioning is the deliberate management of interface changes over time. It applies equally to REST APIs, GraphQL schemas, and gRPC services. The goal is to introduce new features and fixes while keeping existing clients working. REST APIs commonly use versioning in the path or headers, GraphQL relies on schema evolution and deprecation, while gRPC uses Protocol Buffers and semantic versioning. Regardless of approach, changes must be categorized, communicated, and documented. A clear versioning strategy is central to API lifecycle management and long-term platform stability.

Key Concepts

Backward-compatible and breaking changes

A backward-compatible change adds new functionality without disrupting existing clients—think optional new fields, additional endpoints, or fresh filter options. A breaking change alters existing behavior: removing fields, changing required parameters, or renaming endpoints. Breaking changes require a new version or careful migration planning.

REST API versioning

URI versioning and header versioning are the most common strategies for REST. URI versioning uses paths like /v1/products and plays well with caching. Header versioning passes the version through a header such as api-version: 1 or Accept: application/vnd.shop.v2+json. Content negotiation offers flexibility but demands more effort.

GraphQL schema evolution

GraphQL doesn’t use classical path-based versioning. Instead, the schema evolves incrementally. New fields and types can be added without breaking existing queries. Deprecated fields are marked with the @deprecated directive. Clients decide when to switch to new fields.

gRPC and Protocol Buffers versioning

gRPC uses Protocol Buffers for message definitions. New fields can be added as long as they use carefully assigned field numbers. Old clients ignore unknown fields, new clients can handle defaults. Semantic versioning helps communicate Major, Minor, and Patch releases.

Semantic versioning

Semantic versioning uses Major.Minor.Patch notation. Major signifies breaking changes, Minor indicates new backward-compatible features, and Patch marks bug fixes. For external APIs, often only the Major version is publicly advertised to keep complexity down for consumers.

Deprecation and migration

When a version or field should no longer be supported, mark it as deprecated. Use @deprecated for GraphQL, or headers like Deprecation or Sunset for REST. Document the migration path, notify users early, and set a clear end-of-life date.

Versioning in documentation

Documentation must be available for each version, including a changelog and migration guide. Users need to see what changes come with a new version and what steps they must take to upgrade.

Caching and versioning

Path-based versioning is especially simple to cache, since each version has its own URL. With header versioning or GraphQL, caches must be configured to respect the relevant distinctions. Otherwise you risk incorrect cache hits.

Monitoring and usage analytics

Track which versions are in use. This tells you when old versions can safely be retired. Rate limiting and logging per version help identify capacity and problems.

API governance

Larger organizations often establish API governance to standardize version management. Standards for versioning, deprecation, communication, and documentation ensure consistency across multiple teams and APIs.

Practical Example

A company operates both a REST API and a GraphQL API. They introduce a breaking change to customer address data in the REST API.

REST API v1:

GET /v1/customers/42
{
  "id": 42,
  "name": "Musterfirma",
  "address": "Musterstraße 12, 10115 Berlin"
}

REST API v2:

GET /v2/customers/42
{
  "id": 42,
  "name": "Musterfirma",
  "address": {
    "street": "Musterstraße 12",
    "zip": "10115",
    "city": "Berlin",
    "country": "DE"
  }
}

GraphQL schema evolution:

type Customer {
  id: ID!
  name: String!
  address: String @deprecated(reason: "Use addressObject instead")
  addressObject: Address
}

type Address {
  street: String!
  zip: String!
  city: String!
  country: String!
}

With GraphQL, the client can migrate from address to addressObject gradually without changing the API version in the path. With REST, the client moves from v1 to v2.

FAQ: API Versioning

1. What is API versioning?

API versioning is the management of changes to an interface so you can introduce new features without breaking existing clients.

2. What are the most common REST versioning approaches?

REST APIs are typically versioned via URI versioning or header versioning. URI versioning uses paths like /v1/customers, while header versioning passes the version through an HTTP header.

3. How does versioning work with GraphQL?

GraphQL uses schema evolution. New fields are added, old fields are marked with @deprecated. Clients choose when to migrate to new fields.

4. How do you version gRPC APIs?

gRPC APIs use Protocol Buffers and semantic versioning. New fields are added with field numbers, old clients ignore unknown fields.

5. What is semantic versioning?

Semantic versioning uses Major.Minor.Patch notation. Major indicates breaking changes, Minor signifies new backward-compatible features, and Patch covers bug fixes.

6. What is schema evolution?

Schema evolution is the incremental development of an API schema, often without introducing new versions in the path. It’s particularly common in GraphQL and gRPC.

7. What does deprecation mean?

Deprecation marks a version, endpoint, or field as obsolete. Users are informed and given time to migrate.

8. What’s the difference between backward-compatible and breaking changes?

Backward-compatible changes extend the API without disrupting existing clients. Breaking changes alter existing behavior and require a new version or careful migration.

9. What is content negotiation?

Content negotiation uses the Accept header to negotiate version and format. For example: Accept: application/vnd.shop.v2+json. It’s flexible but more complex than URI versioning.

10. How do you communicate the end of an API version?

Communicate the end of an API version through deprecation notices, Sunset headers, email notifications, changelogs, and migration guides. Provide adequate advance notice.

11. What is the Sunset header?

The Sunset header indicates the planned end-of-life of an API version. It’s machine-readable and helps clients automatically detect when a version will be shut down.

12. Should you always maintain many API versions simultaneously?

No. Too many versions increase maintenance overhead and costs. Support only as many versions as necessary and communicate clear retirement dates.

13. How does versioning affect caching?

URI versioning is particularly cache-friendly because different versions have different URLs. With header versioning or GraphQL, caches must recognize the relevant distinguishing factors.

14. What is API governance in the context of versioning?

API governance establishes rules for versioning, deprecation, communication, and documentation. In larger organizations, it ensures consistency and quality across teams and APIs.

15. Which versioning model is best?

There’s no one-size-fits-all model. REST APIs often benefit from URI versioning, GraphQL from schema evolution, and gRPC from Protocol Buffers with semantic versioning. What matters is that your strategy is clear and communicated consistently.

Continue Your API Learning Path

The next article in the API learning path covers Idempotency in API Design: Webhooks and Practical Examples — why idempotent operations are essential for reliable APIs.

References

Recommended Books on API Development

If you want to dive deeper into API versioning, API design, and software architecture, we recommend these books:

API Development

Books about API design, REST, GraphQL, OpenAPI and API architecture

Designing Data-Intensive Applications von Martin Kleppmann

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

API Design Patterns von JJ Geewax