Skip to main content

API versioning and compatibility

This page describes the Cloud Video Kit (CVK) API versioning and compatibility rules.

Contract​

Cloud Video Kit will strictly adhere to the above compatibility standards. If a change is breaking and mandatory for business or technical reasons, a new major version will be introduced (for example, /v2/).

Backward-compatible changes​

The following changes are considered backward-compatible.

API surface​

  • Adding new API resources (new endpoints or routes within an existing API family).
  • Adding new optional request parameters to existing API methods (query, path where applicable, or body), for any HTTP method, as long as the parameter is truly optional and existing behaviour does not change for clients that omit it.

Example: if existing methods are POST …/recordings, GET …/recordings/{id}, DELETE …/recordings/{id}, then adding another method in the same module (for example, PATCH …/recordings/{id}) is acceptable when it follows the same compatibility rules.

Request parameters​

  • Adding a new optional query parameter (for example, GET …/recordings/abc123 → GET …/recordings/abc123?includeMetadata=true). Clients that ignore unknown parameters continue to work.

JSON responses​

  • Adding new properties to existing API response objects. Clients that ignore unknown fields continue to work.

Example:

// Before
{ "id": "ord_123", "amount": 100 }

// After (new optional field)
{ "id": "ord_123", "amount": 100, "currency": "USD" }
  • Changing the order of properties in JSON objects. JSON object property order is not significant; clients must not depend on ordering.

Example:

// Before
{ "id": "ord_123", "amount": 100 }

// After (same data, different key order)
{ "amount": 100, "id": "ord_123" }

Webhooks​

  • Adding new event types. Webhook consumers that ignore unknown event types remain unaffected.

Breaking changes​

The following changes are breaking. If they are required, they belong behind a new major API version, not as silent changes within an existing major version.

HTTP status codes and error behaviour​

  • Changing HTTP status codes or behaviour tied to status codes or application error codes (for example, codes such as those described in Error codes). Clients that rely on specific codes or combinations can break.

Example: changing a situation that previously returned 200 OK or 400 Bad Request so that it now returns 202 Accepted or 422 Unprocessable Entity (or any other change where clients assumed the old status) is breaking.

Endpoints and URLs​

  • Changing or removing endpoints (including paths that used to exist returning success and now returning 404 for the same client usage).
  • Renaming paths so the old path no longer works (for example, GET /v1/orders → GET /v1/order).

Response shape and fields​

  • Changing response structure (nesting, wrapping, or naming of properties) so that clients that read a flat field (for example, response.id) no longer find it at the same path.

Example:

// Before
{ "id": "ord_123", "amount": 100 }

// After (nested — breaking for clients expecting top-level id)
{ "order": { "id": "ord_123", "amount": 100 } }
  • Removing fields from responses.
  • Changing data types of existing fields (for example, numeric amount to string "100"), which can break parsing and validation.

Request parameters and validation​

  • Changing request parameters in a breaking way (for example, renaming customerId to userId while removing support for the old name).
  • Making a previously optional parameter required.
  • Adding a new required parameter without a new major version.
  • Adding a new validation rule to an existing parameter so that requests that were previously valid are rejected (for example, stricter numeric bounds).
  • Adding a required request header that existing clients do not send (for example, a mandatory idempotency or correlation header on an existing operation).

Enumerations​

  • Adding a new value to an enumeration that is not documented or designed as extensible, when clients use a strict switch (or equivalent) without a default case — those clients can fail when they see the new value.
  • Removing an enum value, or renaming the string/value of an enum constant, when clients compare to fixed literals.

Authorization and security​

  • Modifying authorization requirements (for example, requiring an extra header or credential that was not required before), which causes existing integrations to fail.

Collections and pagination​

  • Introducing paging or changing the top-level structure of an existing collection response (for example, from a bare JSON array to a wrapped object with data, hasMore, etc.) is breaking when clients assumed the old shape.

Example:

// Before
[ { "id": "1" }, { "id": "2" } ]

// After
{
  "data": [ { "id": "1" }, { "id": "2" } ],
  "hasMore": false
}

Contact​

If you have questions about API behaviour or upgrades, contact us or raise a request.