Versioning
Versioning
Section titled “Versioning”The public REST API is versioned in the URL path. The current version is v1:
/api/v1/...You can confirm the running package version with GET /api/v1/version. The OpenAPI document at /api/v1/openapi.json is the machine-readable contract for that version.
Backwards compatibility within v1
Section titled “Backwards compatibility within v1”Collingo aims to keep v1 backwards compatible. Within /api/v1, changes should not break existing clients.
Additive (non-breaking) changes may appear in v1 without a new major version, for example:
- New optional request fields (omitting them keeps previous behavior)
- New response fields (clients should ignore unknown fields)
- New endpoints under
/api/v1 - New optional query parameters with safe defaults
Clients should treat unknown JSON fields as ignorable and avoid depending on exact field order.
Breaking changes and v2
Section titled “Breaking changes and v2”If a change would break existing clients — for example removing a field, renaming a path, changing response shapes in an incompatible way, or altering required request semantics — Collingo will introduce a new major version as a separate prefix:
/api/v2/...Existing /api/v1 clients continue to work against v1. Migrating to v2 is opt-in when you are ready.
Recommendations
Section titled “Recommendations”- Pin integrations to
/api/v1explicitly (do not invent unversioned paths). - Prefer the published OpenAPI document when generating clients.
- Ignore unknown response fields so additive v1 updates stay compatible with your code.