Why version your APIs

Developers build applications that depend on your API's behavior. Versioning lets you improve the API without breaking those applications, and gives developers a predictable path when change is unavoidable.

Choose a versioning scheme

Use a major version number in the API path and in the OpenAPI info.version field.

https://api.example.com/v1/orders
https://api.example.com/v2/orders

Within a major version, use semantic versioning (MAJOR.MINOR.PATCH) in the specification:

• MAJOR – Breaking changes. Published as a new major version (v2).
• MINOR – New, backward-compatible functionality.
• PATCH – Backward-compatible fixes and documentation updates.

What counts as a breaking change

The following changes require a new major version:

• Removing or renaming an endpoint, parameter, or response field.
• Changing a field's data type, format, or meaning.
• Making an optional parameter required.
• Adding a new required request field.
• Changing authentication or authorization requirements.
• Changing error codes or response structure that clients rely on.

What is safe to change

These changes are backward-compatible and can be released within the current version:

• Adding a new endpoint.
• Adding an optional request parameter.
• Adding a new field to a response.
• Adding a new enum value, if clients are documented to ignore unknown values.
• Improving descriptions and examples.

Publish multiple versions

Publish each major version as its own API version in the portal so developers can compare and migrate on their own schedule.

1. Update the OpenAPI specification with the new version number.
2. In Konnect, open Dev Portal and go to Published APIs.
3. Select the API, then add the new version.
4. Publish the new version and confirm the documentation renders correctly.
5. Keep the previous version published until its deprecation window ends.

Deprecate and retire a version

Follow a consistent process so developers are never surprised.

1. Announce. Notify developers when the replacement version is available.
2. Mark as deprecated. Set deprecated: true on affected operations in the specification and note the replacement in the description.
3. Provide a migration guide. Document what changed and how to update.
4. Set a window. Support the deprecated version for a defined period, such as six to twelve months.
5. Send reminders. Notify developers as the retirement date approaches.
6. Retire. Unpublish the version once the window ends.

paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      deprecated: true
      description: Deprecated. Use `GET /v2/orders` instead. This endpoint will be retired on the announced date.

Best practices

• Avoid breaking changes whenever possible. Prefer additive changes.
• Document your versioning and deprecation policy and keep it easy to find.
• Keep the number of supported versions small.
• Use release notes to describe every change.
• Monitor usage of older versions before retiring them.

Next steps

Return to Publish APIs or browse the Guides overview.