Versioning and changes
Every module API carries its major version in the path: /api/desk/v1. Within a version, changes
are backwards compatible:
| Compatible (may happen any time) | Breaking (only in a new version) |
|---|---|
| new endpoints | removing or renaming an endpoint or field |
| new optional request fields and parameters | new required request fields |
| new response fields | changing a field's type or meaning |
| new enum values, event types and error codes | removing enum values |
| new optional headers | changing authentication |
Build your client to tolerate the left column: ignore unknown response fields, handle unknown enum values and error codes gracefully (fall back to the HTTP status).
Deprecation policy
Breaking changes get a new version prefix (/api/desk/v2). The previous version stays available for
at least six months after the new one is released. Deprecated endpoints are marked deprecated
in the OpenAPI documents and in this reference, and every deprecation is announced in the
changelog first.
Where to follow changes
- The product changelog: docs.mbcom.cloud/changelog – searchable and filterable by kind and month.
- The OpenAPI documents of this site (
/openapi/<module>.yaml) always describe what is deployed. Diff them in your CI (for example withoasdiff breaking) to be warned early. - The
info.versionof a document changes with every release of its contract.