---
title: "Versioning"
description: "Introduce changes to your APIs safely with a clear versioning and deprecation policy."
url: "https://developer.collectors.com/guides/publish-apis/versioning"
image: "https://developer.collectors.com/_og/d/c_Ocean.takumi,title_Versioning,description_Introduce+changes+to+your+APIs+safely+with+a+clear+versioning+and+deprecation+policy.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiNFRTA0MDMifX19,p_Ii9ndWlkZXMvcHVibGlzaC1hcGlzL3ZlcnNpb25pbmci,s_KFODqDcTdj7lH7pt.png"
---

## Versioning

Introduce changes to your APIs safely with a clear versioning and deprecation policy.

## [Why version your APIs](#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](#choose-a-versioning-scheme)

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

```text
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](#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](#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-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](#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.

```yaml
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](#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](#next-steps)

Return to [Publish APIs](https://developer.collectors.com/guides/publish-apis) or browse the [Guides](https://developer.collectors.com/guides) overview.