ConnectCloud Developers

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 with oasdiff breaking) to be warned early.
  • The info.version of a document changes with every release of its contract.

View as Markdown