Plan for API version changes

The automation orchestrator REST API uses URL path versioning to manage API evolution and protect existing integrations from breaking changes. You can rely on the versioning scheme and deprecation policy to plan stable, long-term integrations.

Client compatibility requirements

To maintain compatibility across releases, follow these requirements in all API clients and integrations:

  • Ignore unknown response fields. When the server adds a new field to a response, your client must not reject the response or fail. This applies to all API consumers, including the generated Python client, the CLI tool, ansible.platform collection modules, and custom integrations.
  • Handle unknown enum values gracefully. When the server adds a new value to a string enum, your client must not crash or error. Log a warning and fall back to a safe default behavior.

These requirements allow the API to introduce non-breaking additive changes in any release without affecting existing integrations.

URL path versioning

The API version is embedded in the URL path prefix. The current version is v1, and all endpoints are served under /api/v1/.

The URL prefix major number matches the OpenAPI info.version major number. When info.version changes from 1.x.y to 2.0.0, the URL prefix changes from /api/v1/ to /api/v2/.

When a new major version is introduced, both the old and new URL prefixes serve live traffic simultaneously. The deprecated version is removed after the minimum notice period.

Semantic versioning management

The OpenAPI info.version field uses Semantic Versioning (MAJOR.MINOR.PATCH) to signal the scope of API surface changes:

Table 1. Semantic version change types
Event Version change
Breaking change (see the following section) Major (1.x.y to2.0.0)
Additive, non-breaking change (new endpoint, new optional field, new enum value) Minor
Specification-only change with no API surface impact (description fix, example update, annotation correction) Patch

Before a new major version is introduced, replacements for deprecated items are added in the current version. You can migrate to each replacement before the new major version is released. When the new major version is released, all deprecated items are removed.

Breaking-change policy

Breaking changes are detected automatically during development and are blocked from release without an explicit review and approval process.

Changes classified as breaking

No breaking changes are permitted within a version. A breaking change requires a new major version. The following list is not exhaustive; other changes can also be classified as breaking.

  • Removing an endpoint, including deprecated endpoints.
  • Removing any field from the response schema, whether required, optional, or deprecated.
  • Renaming a field without maintaining an alias during a deprecation period.
  • Making an optional request field required.
  • Adding a required request field.
  • Changing the type of an existing field.
  • Making an existing response field nullable (string to string | null).
  • Making an existing request field non-nullable (string | null to string).
  • Narrowing the set of accepted input values or widening the set of possible output values.
  • Changing authentication or authorization requirements for an endpoint.
  • Changing response status codes for existing conditions, except status code corrections described in the following section.
  • Removing an enum value from a constrained field.
  • Tightening validation constraints, such as reducing maximum length or adding patterns.
  • Changing default values of request fields.
  • Changing behavior without changing the type signature.

Status code corrections within a version

Within v1, status codes can be corrected to more semantically accurate values without a new major version. For example, an endpoint that returns 401 Unauthorized for an insufficient-permissions condition can be corrected to 403 Forbidden.

This exception applies only to status code corrections. All other changes in the breaking-change classification require a new major version.

Changes classified as non-breaking

The following changes can be introduced in any release:

  • Adding a new endpoint.
  • Adding a new optional request parameter or field.
  • Adding a new response field.
  • Adding a new enum value to an existing field.
  • Adding a new optional query parameter.
  • Changing human-readable error messages while keeping the error code and structure stable.

Design your integrations to tolerate non-breaking changes by following the client compatibility requirements.

Deprecation policy

Feature-level deprecation

Individual fields, endpoints, or parameters can be deprecated within a version. When a breaking change is needed, the replacement is introduced alongside the deprecated item in the current version. Both coexist until the deprecated item is removed in a new major version. The deprecated item is never removed within the same version.

For example, if a field needs to change type, a new field with the correct type is added alongside the original. Both fields are served simultaneously. The original is marked deprecated and is only removed when a new major version is released.

Version-level deprecation

When a new API major is released, the previous version is deprecated. Both versions run in parallel for at least one product lifecycle before the old version is removed.

Minimum notice period

Deprecation notices span at least one full lifecycle epoch before the deprecated item is removed.

This minimum notice period applies to both feature-level and version-level deprecation.