API Versioning

The version of an API is a segment of its URL, after the module: /api/<module>/v2/…. Every path in the two specs has it, except the two staff token routes (/api/token/, /api/token/refresh/). Checked on the specs of this portal:

$ grep -h "^  /api/" public/openapi/volkanos-api-*.yaml | grep -vc "/v2/"
2

The demo backend, https://demo-api.entirius.com, serves them: /api/matrix/v2/sloik-pl/products/ is the storefront product list, /api/pim/v2/admin/channels/ the admin channel list.

What v2 Means

v2 names a contract that every endpoint under it keeps, whichever module serves it:

• One error envelope. error, message, debug_id, details: Errors.
• Two list envelopes. Counted on admin lists, uncounted on storefront catalog lists: Pagination.
• Typed bodies. Requests and responses are Pydantic schemas with a description and an example on every field.
• A generated spec. The OpenAPI description is produced from the code and never edited by hand, so the explorers show what the backend does.

The rules a module follows to keep that contract: API v2 Standard.

A change that breaks a caller of a v2 endpoint is a major release of the module that owns it, with the step to take in its changelog: Versioning and Upgrades.

Legacy v1

Routes from before the standard still answer, for clients that were built on them: the PIM viewer, content (/api/contentdb/v1/…), and customer accounts with their tokens (/api/accounts/v1/<channel_idx>/…). They are not in the specs, have no generated description, and get no new features. GET https://demo-api.entirius.com/api/contentdb/v1/ still answers 200. Their errors and lists do not follow the v2 envelopes.

One of them is still on the path of a new storefront: the customer token route, which the v2 cart, order and price operations rely on (Customer Tokens). Build everything else on v2. New endpoints are v2 only.

Spec Version

info.version in a spec is the version of the backend service it was generated from, which is the platform version. Both specs in this portal and the demo backend come from the same release. The release it belongs to and the module versions that release pins are under Status.

Packages follow semantic versioning: patch for a fix, minor for a capability that breaks no caller, major when an interface breaks. How a release is cut: Releases.

Sources

• main/settings.py of the service: the spec version is the project version.
• django_utils/api/v2_errors.py: the v2 error envelope.
• django_pim/urls.py, django_contentdb/urls.py and django_accounts/urls.py: the legacy routes next to the v2 ones.