---
title: "API Versioning Strategies and Best Practices - API7.ai"
description: "Learn when to version an API, compare URI, header, query, and media-type strategies, and choose a stable approach for REST APIs and API gateways."
url: "https://api7.ai/learning-center/api-101/api-versioning"
---

[Skip to article](#column-content)

Column contentsAPI 101

[API 101](https://api7.ai/learning-center/api-101)

Search this column

01 API Fundamentals

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=fundamentals)[1. Introduction to APIs: Definition and Importance](https://api7.ai/learning-center/api-101/what-is-api)[2. RESTful API Best Practices: Architecture, Methods, and Examples](https://api7.ai/learning-center/api-101/restful-api-best-practices)[3. SOAP vs REST: Differences, Examples, and When to Use Each](https://api7.ai/learning-center/api-101/soap-vs-rest-differences)[4. GraphQL: A New Approach to APIs](https://api7.ai/learning-center/api-101/what-is-graphql)[5. gRPC: High-Performance RPC Framework](https://api7.ai/learning-center/api-101/what-is-grpc)[6. Webhooks: Real-Time Communication Between Applications](https://api7.ai/learning-center/api-101/what-is-webhooks)[7. API Endpoints: Designing and Managing for Scalability and Security](https://api7.ai/learning-center/api-101/what-are-api-endpoints)[8. HTTP Methods: GET, POST, PUT, PATCH, DELETE & More](https://api7.ai/learning-center/api-101/http-methods-in-apis)[9. API Rate Limiting Best Practices and Algorithms](https://api7.ai/learning-center/api-101/api-rate-limiting)[10. API Versioning Strategies and Best Practices](https://api7.ai/learning-center/api-101/api-versioning)

02 API Development and Design

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=design)[11. How to Build an API: From Design to Deployment](https://api7.ai/learning-center/api-101/build-your-first-api)[12. API Documentation: Tools and Techniques](https://api7.ai/learning-center/api-101/api-documentation-tools-and-techniques)[13. OpenAPI Specification Guide: OAS, Examples, and Best Practices](https://api7.ai/learning-center/api-101/openapi-specification)[14. API Mocking: Testing Without a Backend](https://api7.ai/learning-center/api-101/api-mocking)[15. API Error Handling: Status Codes, Error Responses, and Best Practices](https://api7.ai/learning-center/api-101/error-handling-apis)[16. Authentication and Authorization in APIs](https://api7.ai/learning-center/api-101/authentication-authorization-apis)[17. OAuth 2.0: Secure API Access](https://api7.ai/learning-center/api-101/oauth-2.0-secure-api-access)[18. API Gateways: Managing and Securing Traffic](https://api7.ai/learning-center/api-101/api-gateways-managing-securing-traffic)[19. Microservices and APIs: Designing Modular Applications](https://api7.ai/learning-center/api-101/microservices-apis-modular-application-design)[20. API Orchestration: Combining Multiple Services](https://api7.ai/learning-center/api-101/api-orchestration-combining-services)

03 API Security

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=security)[21. How to Avoid Common Vulnerabilities](https://api7.ai/learning-center/api-101/how-to-avoid-common-api-vulnerabilities)[22. Implementing JWT for API Security](https://api7.ai/learning-center/api-101/implementing-jwt-for-api-security)[23. Rate Limiting and Throttling: Protecting Your API](https://api7.ai/learning-center/api-101/rate-limiting-and-throttling)[24. API Security Testing Tools and Techniques for Modern APIs](https://api7.ai/learning-center/api-101/api-security-testing-tools-and-techiniques)[25. CORS in APIs: Handling Cross-Origin Requests](https://api7.ai/learning-center/api-101/understanding-cors-in-apis)[26. Data Encryption in API Communication](https://api7.ai/learning-center/api-101/data-encryption-in-api-communication)[27. API Security Best Practices: Protecting Your Digital Front Door](https://api7.ai/learning-center/api-101/api-security-best-practices)[28. API Tokens Explained: Usage, Security, and Best Practices](https://api7.ai/learning-center/api-101/api-tokens-and-their-usage)[29. Securing APIs in Serverless Architectures](https://api7.ai/learning-center/api-101/secure-apis-in-serverless-architectures)[30. API Security in the Age of IoT](https://api7.ai/learning-center/api-101/api-security-in-the-age-of-iot)

04 API Integration

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=integration)[31. Integrating Third-Party APIs into Your Application](https://api7.ai/learning-center/api-101/integrate-third-party-apis)[32. API Aggregation: Combining Multiple APIs](https://api7.ai/learning-center/api-101/api-aggregation-combining-multiple-apis)[33. Real-Time Data with Streaming API](https://api7.ai/learning-center/api-101/real-time-data-with-streaming-apis)[34. Handling API Pagination: Fetching Large Data Sets](https://api7.ai/learning-center/api-101/handling-api-pagination)[35. Error Handling When Consuming APIs](https://api7.ai/learning-center/api-101/error-handling-when-consuming-apis)[36. API Integration Testing: Ensuring Reliability](https://api7.ai/learning-center/api-101/api-integration-testing-ensuring-reliability)[37. Working with Rate Limits in Third-Party APIs](https://api7.ai/learning-center/api-101/working-with-rate-limits-in-third-party-apis)[38. Automating Workflows with APIs](https://api7.ai/learning-center/api-101/automating-workflows-with-apis)[39. API Integration in Mobile Applications](https://api7.ai/learning-center/api-101/api-integration-in-mobile-applications)[40. How to Overcome API Integration Challenges](https://api7.ai/learning-center/api-101/how-to-overcome-api-integration-challenges)

05 API Management

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=management)[41. API Lifecycle Management: From Development to Retirement](https://api7.ai/learning-center/api-101/api-lifecycle-management)[42. Monitoring API Performance: Tools and Metrics](https://api7.ai/learning-center/api-101/api-performance-monitoring)[43. API Analytics: Understanding Usage Patterns](https://api7.ai/learning-center/api-101/api-analytics-guide)[44. Monetizing Your API: Strategies and Models](https://api7.ai/learning-center/api-101/api-monetization-strategies-models)[45. Scaling APIs: Best Practices for High Traffic](https://api7.ai/learning-center/api-101/scaling-api-high-traffic-best-practices)[46. API Governance Policies and Standards Guide](https://api7.ai/learning-center/api-101/api-governance-policies-standards-guide)[47. API Developer Portal Guide: Features, Onboarding, and Engagement](https://api7.ai/learning-center/api-101/developer-portal-guide-engaging-api-users)[48. Rate Limiting Strategies for API Management](https://api7.ai/learning-center/api-101/rate-limiting-strategies-for-api-management)[49. API Breaking Changes: Deprecation and Migration Guide](https://api7.ai/learning-center/api-101/api-versioning-managing-changes-over-time)[50. Choosing the Right API Management Platform](https://api7.ai/learning-center/api-101/choosing-the-right-api-management-platform)

06 Emerging API Practices

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=trends)[51. Serverless APIs: Building Scalable Applications](https://api7.ai/learning-center/api-101/serverless-apis)[52. API-First Development: From Contract to Production](https://api7.ai/learning-center/api-101/api-first-development)[53. Hypermedia APIs: HATEOAS and Its Applications](https://api7.ai/learning-center/api-101/hypermedia-apis)[54. The Role of AI in API Development](https://api7.ai/learning-center/api-101/ai-in-api-development)[55. APIs in IoT: Connecting Devices](https://api7.ai/learning-center/api-101/apis-in-iot)[56. REST and GraphQL APIs: Architecture, Caching, and Gateways](https://api7.ai/learning-center/api-101/graphql-vs-rest)[57. The Rise of API Marketplaces](https://api7.ai/learning-center/api-101/rise-of-api-marketplaces)[58. Event-Driven APIs: Designing for Real-Time](https://api7.ai/learning-center/api-101/event-driven-api-design-real-time)[59. Low-Code/No-Code API Development](https://api7.ai/learning-center/api-101/low-code-no-code-api-development-guide)[60. API Development Trends: The Future of APIs for Modern Teams](https://api7.ai/learning-center/api-101/future-and-trends-of-apis)

07 Industry API Applications

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=industries)[61. Payment Gateway APIs: Integrating Stripe and PayPal](https://api7.ai/learning-center/api-101/stripe-vs-paypal-api-integration-guide)[62. Social Media APIs: Facebook, Twitter, and Instagram](https://api7.ai/learning-center/api-101/social-media-apis)[63. Maps & Geolocation APIs: Google Maps, Mapbox, and OSM](https://api7.ai/learning-center/api-101/mapping-and-geolocation-apis)[64. E-commerce APIs: Building Modern Online Stores](https://api7.ai/learning-center/api-101/e-commerce-apis)[65. Healthcare APIs: Connecting Medical Data](https://api7.ai/learning-center/api-101/healthcare-apis)[66. Financial APIs: Accessing Banking Services](https://api7.ai/learning-center/api-101/financial-apis)[67. Travel and Booking APIs: Integrating Flight and Hotel Data](https://api7.ai/learning-center/api-101/travel-and-booking-apis)[68. Music and Video Streaming APIs: Spotify and YouTube](https://api7.ai/learning-center/api-101/music-and-video-streaming-apis)[69. Weather APIs: Accessing Meteorological Data](https://api7.ai/learning-center/api-101/weather-apis)[70. Sports Data APIs: Features, Use Cases, and Integration Tips](https://api7.ai/learning-center/api-101/sports-data-apis)

08 Tools and Platforms

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=tools)[71. What Is Postman? API Development Platform Guide](https://api7.ai/learning-center/api-101/postman-api-development-environment)[72. Swagger: Designing and Documenting APIs](https://api7.ai/learning-center/api-101/swagger-designing-and-documenting-apis)[73. Insomnia API Client: Debug, Test, and Design APIs](https://api7.ai/learning-center/api-101/insomnia-rest-client-for-debugging)[74. What Is Apigee? API Management Features and Architecture](https://api7.ai/learning-center/api-101/apigee-api-management-platform)[75. Building Serverless APIs with AWS API Gateway](https://api7.ai/learning-center/api-101/aws-api-gateway-building-serverless-apis)[76. Apache APISIX: Open-Source API Gateway and Enterprise Support](https://api7.ai/learning-center/api-101/apache-apisix-open-source-api-gateway)[77. MuleSoft: Connecting Applications and Data](https://api7.ai/learning-center/api-101/mulesoft-connecting-applications-and-data)[78. RapidAPI Guide: Discovering, Testing, and Connecting to APIs](https://api7.ai/learning-center/api-101/rapidapi-discovering-and-connecting-to-apis)[79. Firebase: Backend as a Service](https://api7.ai/learning-center/api-101/firebase-backend-as-a-service)[80. Auth0: Complete Authentication and Authorization Platform](https://api7.ai/learning-center/api-101/auth0-authentication-authorization-platform)

09 API Testing

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=testing)[81. Automated API Testing: Tools and Techniques](https://api7.ai/learning-center/api-101/automated-api-testing-tools-and-techniques)[82. Load Testing Your API: Ensuring Performance at Scale](https://api7.ai/learning-center/api-101/load-testing-your-api-ensuring-performance)[83. Mocking APIs for Testing: Accelerating Development and Improving Quality](https://api7.ai/learning-center/api-101/mocking-apis-for-testing-purposes)[84. Contract Testing in API Development: Ensuring Reliable Integration](https://api7.ai/learning-center/api-101/contract-testing-in-api-development)[85. Postman API Testing Automation: Newman, CLI, and CI/CD](https://api7.ai/learning-center/api-101/using-postman-for-api-testing)[86. Continuous Integration and API Testing](https://api7.ai/learning-center/api-101/continuous-integration-and-api-testing)[87. Security Testing for APIs: Protecting Your API from Vulnerabilities](https://api7.ai/learning-center/api-101/security-testing-for-apis)[88. Handling API Deprecations in Testing: Strategies for Smooth Transitions](https://api7.ai/learning-center/api-101/handling-api-deprecations-in-testing)[89. Testing GraphQL APIs: Challenges and Solutions](https://api7.ai/learning-center/api-101/testing-graphql-apis-challenges-and-solutions)[90. API Test Automation Frameworks: A Comparative Study](https://api7.ai/learning-center/api-101/api-test-automation-frameworks-comparative-study)

10 Documentation and Developer Experience

[View this topic · 10](https://api7.ai/learning-center/api-101?topic=documentation)[91. Writing Clear and Concise API Documentation](https://api7.ai/learning-center/api-101/writing-clear-and-concise-api-documentation)[92. Tools for Generating API Documentation](https://api7.ai/learning-center/api-101/tools-for-generating-api-documentation)[93. Interactive API Documentation for Developer Experience](https://api7.ai/learning-center/api-101/interactive-api-documentation)[94. Maintaining Documentation for Multiple API Versions](https://api7.ai/learning-center/api-101/maintaining-documentation-for-multiple-api-versions)[95. Using OpenAPI for API Documentation](https://api7.ai/learning-center/api-101/using-openapi-for-api-documentation)[96. Best Practices for Documenting API Error Responses](https://api7.ai/learning-center/api-101/best-practices-for-documenting-api-error-responses)[97. Incorporating Code Samples in API Documentation](https://api7.ai/learning-center/api-101/incorporating-code-samples-in-api-documentation)[98. API Documentation for Non-Developers](https://api7.ai/learning-center/api-101/api-documentation-for-non-developers)[99. Translating API Documentation for Global Audiences](https://api7.ai/learning-center/api-101/translating-api-documentation-for-global-audiences)[100. How to Measure API Documentation Effectiveness](https://api7.ai/learning-center/api-101/measuring-api-documentation-effectiveness)

[API 101](https://api7.ai/learning-center/api-101)[API Fundamentals](https://api7.ai/learning-center/api-101?topic=fundamentals)

On this page

On this page

- [When Does an API Need a New Version?](#when-does-an-api-need-a-new-version)

- [Common API Versioning Strategies](#common-api-versioning-strategies)

  - [URI Path Versioning](#uri-path-versioning)
  - [Request Header Versioning](#request-header-versioning)
  - [Query Parameter Versioning](#query-parameter-versioning)
  - [Media Type Versioning](#media-type-versioning)

- [API Versioning Strategy Comparison](#api-versioning-strategy-comparison)

- [How to Choose a Versioning Strategy](#how-to-choose-a-versioning-strategy)

- [API Versioning Best Practices](#api-versioning-best-practices)

  - [Publish a Compatibility Policy](#publish-a-compatibility-policy)
  - [Version the Contract, Not Every Deployment](#version-the-contract-not-every-deployment)
  - [Keep the Selection Mechanism Consistent](#keep-the-selection-mechanism-consistent)
  - [Document Every Active Version](#document-every-active-version)
  - [Test Consumer-Relevant Compatibility](#test-consumer-relevant-compatibility)
  - [Treat Semantic Versioning Carefully](#treat-semantic-versioning-carefully)
  - [Limit Simultaneously Active Versions](#limit-simultaneously-active-versions)

- [API Gateway Version Routing](#api-gateway-version-routing)

- [Versioning REST, GraphQL, and gRPC APIs](#versioning-rest-graphql-and-grpc-apis)

- [FAQ](#faq)

  - [What is the best API versioning strategy?](#what-is-the-best-api-versioning-strategy)
  - [Should every API change create a new version?](#should-every-api-change-create-a-new-version)
  - [Is adding a response field always backward compatible?](#is-adding-a-response-field-always-backward-compatible)
  - [How should an old API version be retired?](#how-should-an-old-api-version-be-retired)

- [Related Guides](#related-guides)

Article 10

# API Versioning Strategies and Best Practices

API7.ai

March 25, 2025

API versioning is the practice of exposing and managing incompatible API contracts without forcing every consumer to migrate at the same moment. A version identifies the contract a client can rely on; it should not change merely because the backend was redeployed or an internal implementation changed.

This guide compares common versioning strategies and helps you choose one. If you already have a breaking change to release, use the separate [API deprecation and migration guide](https://api7.ai/learning-center/api-101/api-versioning-managing-changes-over-time) for rollout, communication, monitoring, and retirement steps.

## When Does an API Need a New Version?

Create a new externally visible version when a change breaks a documented client contract and compatibility cannot reasonably be preserved.

Common breaking changes include:

- removing or renaming a field that clients use;
- changing a field's type or meaning;
- making an optional request field required;
- removing an endpoint or supported operation;
- changing authentication requirements in a way existing clients cannot satisfy;
- changing pagination, error, or idempotency behavior promised by the contract.

Many changes do not require a new version:

- an internal refactor with the same external behavior;
- a backward-compatible bug fix;
- a new optional request field;
- a new endpoint;
- a response field added under a contract that explicitly permits unknown fields.

Compatibility depends on real consumers, not only the provider's intent. A strict client can break when a response gains a field, even if the provider considers the change additive. Use consumer tests and telemetry to validate assumptions.

## Common API Versioning Strategies

### URI Path Versioning

The version appears in the path:

```
GET /v1/orders/123
GET /v2/orders/123
```

The version is visible in logs, documentation, caches, and routing rules. This makes path versioning straightforward for public HTTP APIs, but it also creates a distinct URI space for each major contract.

### Request Header Versioning

The client sends a dedicated version header:

```
GET /orders/123
API-Version: 2026-09-01
```

The resource path remains stable, while infrastructure selects behavior from the header. Every cache, gateway, client library, and observability tool must preserve and account for the version header.

### Query Parameter Versioning

The version is a query parameter:

```
GET /orders/123?version=2
```

This is visible and easy to try, but providers must ensure caches and routing rules treat the parameter as part of the contract rather than ignoring it.

### Media Type Versioning

The client requests a version through content negotiation:

```
GET /orders/123
Accept: application/vnd.example.orders-v2+json
```

This keeps the path stable and can distinguish representations, but it adds complexity to clients, documentation, caching, and debugging.

## API Versioning Strategy Comparison

| Strategy        | Client visibility | Routing and debugging                         | Main trade-off                         |
| --------------- | ----------------- | --------------------------------------------- | -------------------------------------- |
| URI path        | High              | Usually straightforward                       | Creates versioned resource paths       |
| Header          | Medium            | Requires header-aware tooling                 | Version is not visible in the URL      |
| Query parameter | High              | Straightforward if the parameter is preserved | Easy to omit or mishandle in caches    |
| Media type      | Low               | Requires content-negotiation support          | Precise but more complex for consumers |

No strategy is universally best. Choose one that your clients, gateway, cache, documentation, and observability stack can support consistently.

## How to Choose a Versioning Strategy

Use these questions before selecting a pattern:

1. **Who controls the clients?** Internal clients can adopt header conventions more easily than a broad public ecosystem.
2. **How will requests be routed?** Confirm the gateway or application can match the chosen path, header, parameter, or media type.
3. **How do caches distinguish versions?** A cache key must not combine responses from incompatible contracts.
4. **How will developers discover the active version?** Documentation, SDKs, examples, and error messages should make it obvious.
5. **How many versions can the team operate safely?** Every active version adds testing, security, documentation, and support work.
6. **What is the retirement process?** A versioning strategy without a migration policy only postpones the hard part.

## API Versioning Best Practices

### Publish a Compatibility Policy

Define what your organization considers breaking and non-breaking. Include request and response schemas, authentication, errors, pagination, rate-limit behavior, and SDK compatibility.

### Version the Contract, Not Every Deployment

Do not expose a new API version for an internal release that preserves the public contract. Unnecessary versions increase client and operational work without adding compatibility value.

### Keep the Selection Mechanism Consistent

Do not use URI versions for one service, custom headers for another, and query parameters for a third without a deliberate reason. A consistent convention improves documentation and gateway policy reuse.

### Document Every Active Version

Publish the contract, examples, known differences, lifecycle state, and migration path for each supported version. Mark examples clearly so developers do not copy requests for a retired version.

### Test Consumer-Relevant Compatibility

Schema comparison is useful, but it is not enough. Run representative consumer workflows against the new version and verify behavior such as errors, pagination, ordering, retries, and idempotency.

### Treat Semantic Versioning Carefully

[Semantic Versioning 2.0.0](https://semver.org/) defines `MAJOR.MINOR.PATCH` rules for a declared public API. Those principles can help classify incompatible and backward-compatible changes, especially for SDKs and published packages. They do not prescribe whether an HTTP API should use a path, header, date, or media type as its runtime version selector.

### Limit Simultaneously Active Versions

Support versions according to an explicit lifecycle policy, not an arbitrary permanent promise. Keep an older version only while its consumer and risk requirements justify the maintenance cost.

## API Gateway Version Routing

An API gateway can route requests to different upstreams when the selected version is visible in a path, header, or query parameter.

```
flowchart LR
    A[Client] --> B[API gateway]
    B -->|/v1 or version=1| C[API v1]
    B -->|/v2 or version=2| D[API v2]
```

Routing does not create a versioning policy by itself. Teams must still define ownership, compatibility tests, documentation, observability, and retirement criteria for each upstream version.

When gradual migration is required, the gateway can also direct a controlled cohort to a new upstream, provided that the routing key and rollback conditions are explicit. See [A/B testing and canary releases with an API gateway](https://api7.ai/learning-center/api-gateway-guide/ab-testing-canary-release-api-gateway) for rollout concepts.

## Versioning REST, GraphQL, and gRPC APIs

- **REST APIs:** Often expose versions through paths or headers, but the correct choice depends on the contract and infrastructure.
- **GraphQL APIs:** Commonly evolve one schema through additive changes and field deprecation. A separate endpoint version may still be needed for incompatible architectural changes.
- **gRPC APIs:** Package and service names can carry version boundaries, while protobuf field-number compatibility rules constrain schema evolution.

The same governance question applies to each style: which changes remain compatible for existing consumers, and how will an incompatible change be introduced and retired?

## FAQ

### What is the best API versioning strategy?

There is no universal best strategy. URI versions are visible and easy to route; headers and media types keep paths stable but require version-aware clients and infrastructure. Choose one convention and support it consistently.

### Should every API change create a new version?

No. Create a new version for incompatible contract changes that cannot be introduced safely within the existing contract. Internal refactors and compatible additions normally do not need a new client-visible version.

### Is adding a response field always backward compatible?

Not always. It is compatible only when clients tolerate unknown fields and the documented contract permits additions. Test representative consumers before assuming compatibility.

### How should an old API version be retired?

Publish the replacement and migration guide, identify affected consumers, run versions in parallel when necessary, communicate deprecation, monitor migration, and retire only when the stated conditions are met. Follow the [API deprecation and migration guide](https://api7.ai/learning-center/api-101/api-versioning-managing-changes-over-time) for the operational sequence.

## Related Guides

- [API Breaking Changes, Deprecation, and Migration](https://api7.ai/learning-center/api-101/api-versioning-managing-changes-over-time)
- [API Lifecycle Management](https://api7.ai/learning-center/api-101/api-lifecycle-management)
- [RESTful API Best Practices](https://api7.ai/learning-center/api-101/restful-api-best-practices)
- [What Is an API Gateway?](https://api7.ai/learning-center/api-gateway-guide/what-is-an-api-gateway)
- [A/B Testing and Canary Releases with an API Gateway](https://api7.ai/learning-center/api-gateway-guide/ab-testing-canary-release-api-gateway)

[Previous article**API Rate Limiting Best Practices and Algorithms**](https://api7.ai/learning-center/api-101/api-rate-limiting)[Next topic · API Development and Design**How to Build an API: From Design to Deployment**](https://api7.ai/learning-center/api-101/build-your-first-api)

On this page

- [When Does an API Need a New Version?](#when-does-an-api-need-a-new-version)

- [Common API Versioning Strategies](#common-api-versioning-strategies)

  - [URI Path Versioning](#uri-path-versioning)
  - [Request Header Versioning](#request-header-versioning)
  - [Query Parameter Versioning](#query-parameter-versioning)
  - [Media Type Versioning](#media-type-versioning)

- [API Versioning Strategy Comparison](#api-versioning-strategy-comparison)

- [How to Choose a Versioning Strategy](#how-to-choose-a-versioning-strategy)

- [API Versioning Best Practices](#api-versioning-best-practices)

  - [Publish a Compatibility Policy](#publish-a-compatibility-policy)
  - [Version the Contract, Not Every Deployment](#version-the-contract-not-every-deployment)
  - [Keep the Selection Mechanism Consistent](#keep-the-selection-mechanism-consistent)
  - [Document Every Active Version](#document-every-active-version)
  - [Test Consumer-Relevant Compatibility](#test-consumer-relevant-compatibility)
  - [Treat Semantic Versioning Carefully](#treat-semantic-versioning-carefully)
  - [Limit Simultaneously Active Versions](#limit-simultaneously-active-versions)

- [API Gateway Version Routing](#api-gateway-version-routing)

- [Versioning REST, GraphQL, and gRPC APIs](#versioning-rest-graphql-and-grpc-apis)

- [FAQ](#faq)

  - [What is the best API versioning strategy?](#what-is-the-best-api-versioning-strategy)
  - [Should every API change create a new version?](#should-every-api-change-create-a-new-version)
  - [Is adding a response field always backward compatible?](#is-adding-a-response-field-always-backward-compatible)
  - [How should an old API version be retired?](#how-should-an-old-api-version-be-retired)

- [Related Guides](#related-guides)
