Versioning

The API must contain a version number, starting at v1, for the initial version. Once the initial version has been released, all other changes need to ensure that they will adhere to the following rules:

Any release of a major change will still allow the previous versions of the API to function for a minimum of 6 months for public APIs, and 1 month for internal APIs, to allow any parties using previous versions to make any necessary changes to use this new version.
The major version number must be included the path for the API, however, the minor or patch version changes will not be in the URL path. This is to ensure that all users of the major version will continue to use the latest minor/patch version of the API, resulting in minimal work for the API consumers to use the API.
The version will be applied at each API grouping and not on the whole internal or public API. e.g. the Media API will be versioned by /media/v1 or /media/v2.

Minor / Patch (Non-Breaking Changes)

A change is considered non-breaking if it does not invalidate previously valid requests and does not alter the expected contract for existing API consumers.

Non-breaking changes MAY include:

Adding new output fields.
Adding new optional input fields.
Adding new endpoints.
Marking endpoints as deprecated.
Relaxing validation rules (e.g. reducing minimum length, widening enums).

Non-breaking changes:

MUST NOT introduce stricter validation rules on existing fields.
MUST NOT cause previously valid requests to fail.
MUST NOT alter the expected contract for existing consumers.
Non-breaking changes do not require a major version bump.

Major (Breaking Changes)

A change is considered breaking if it may cause a previously valid request to fail or alters the expected contract for API consumers.

Breaking changes MAY include:

Removing input or output fields.
Removing endpoints previously marked as deprecated.
Making fields required that were previously optional.
Tightening validation rules (e.g. increasing minimum length, narrowing enums).
Changing field types.
Changing response structure or semantics.

Any release of a breaking change MUST allow the previous version to continue functioning for:

A minimum of 6 months for public APIs.
A minimum of 1 month for internal APIs.

This support window governs version availability, not enforcement timing.

API Change Governance & Release Management

This section defines additional governance controls introduced to strengthen API stability and prevent unintended breaking changes.

Schema Change Rules

Published API schemas represent a contractual interface with API consumers.

Major Version Process Flow

Up to two major versions per year (unless extenuating circumstances)
During each 6-month window, minor/patch versions are made and applied to the current major
Proposed major changes are captured in pre-release versions of the spec
Spec is consulted with stakeholders during the major release window
Pre-release (Alpha/Beta) customers are given early access (if applicable)
On major release (GA):
- announced to customers
- clock starts on previous version being retired

Documentation

All APIs, both internal and external, must have an OpenAPI specification that describes the endpoints of the API and their input and output data structures. The specification should be written in the current version of the OpenAPI specification, which at the time of writing this document is v3.1.0 OpenAPI Specification v3.2.0.

The Public API specification will be published in the https://docs.zitcha.com/ page that will be accessible to retailers and third parties.

Deprecations

When an endpoint is marked as deprecated then a new deprecated header will be added with the timestamp that the API was marked as deprecated. This is to indicate to the API consumer when the endpoint was marked as deprecated and will be removed in the next version.

The OpenAPI specification must be updated for the endpoint to have the deprecated property set to true Paths and Operations.

Testing

Zitcha performs the following testing against all API versions as part of the SDLC:

Contract Testing
Automated End-to-end Testing
Automated and manual code reviews
Automated breaking change checks