What should I use to manage versioning and deprecation for APIs?

For API versioning and deprecation, the best choice depends on how your API is exposed, but in practice you usually want a combination of API management + documentation + lifecycle policy.

Good options

• API Gateway / API Management platform
  Use this to route requests by version, control traffic, and publish deprecation notices.
  Examples:

  • AWS API Gateway
  • Azure API Management
  • Apigee
  • Kong
  • Tyk

• OpenAPI / Swagger
  Use this to define and document versions consistently. It helps you communicate what changed and what is deprecated.

• Semantic versioning for the API contract
  Common approach:

  • MAJOR = breaking changes
  • MINOR = backward-compatible additions
  • PATCH = bug fixes / non-contract changes

• Deprecation headers and docs Add deprecation metadata in responses and documentation, such as:

  • Deprecation: true
  • Sunset: <date>
  • Link: <migration guide>

• Release and migration policy Define:

  • how long old versions are supported
  • when deprecation notices are issued
  • how consumers are migrated
  • when old endpoints are removed

Practical recommendation

If you’re building a production API, use:

1. OpenAPI for contract/documentation
2. An API management gateway for routing and governance
3. Semantic versioning + deprecation headers
4. A formal deprecation policy with sunset dates

Simple rule of thumb

• Small/internal API: OpenAPI + semantic versioning may be enough.
• Public/enterprise API: API management platform + OpenAPI + deprecation policy.

If you want, I can also recommend a specific toolset based on your stack, like AWS, Azure, Kubernetes, Node.js, or .NET.