API versioning

The /v1 contract grows without requiring existing clients to change.

Requests

New operations and optional request fields are additive. Existing allowed enum values remain accepted; adding request enum values is additive. A new required request field, a narrower accepted value, a removed operation, or another incompatible change requires /v2.

Responses

New response fields are additive. Ignore fields you do not use. Response enums are extensible, including webhook event types and error codes: the documented values are known values, not a complete set. Accept unknown values and use a safe fallback rather than an exhaustive switch that throws. The @moq/pro response types accept future values; request enums still describe the values the server currently accepts.

The OpenAPI contract marks these sets with x-extensible-enum. Removing a response field or changing its type incompatibly requires /v2.

Deprecation

Every announced deprecation appears in the deprecation ledger, with the affected operations, replacement, announcement date, deprecation date and sunset date. Affected responses send Deprecation, Sunset and a Link with rel="deprecation" pointing to that entry.

Deprecation uses an @-prefixed Unix timestamp (RFC 9745); Sunset uses an HTTP date (RFC 8594). Deprecation announces migration; it does not change an operation's behavior. An incompatible replacement belongs in /v2, and an announced date does not make a breaking /v1 change additive.