Skip to content

Reference · current version 1.0.0

Versioning and deprecation

The REST contract follows semantic versioning and is frozen at 1.0.0. Every response carries the version it follows, so you and a support ticket can say exactly which contract was served.

Response header
API-Version: 1.0.0

The SDKs expose it as ravelo.apiVersion (TypeScript) and client.api_version (Python).

What the version numbers mean

ChangeVersionExamples
Backwards compatible additionminor (1.1.0)A new endpoint, an optional request field, a new response field, a new error code, a new enum value in a response.
Documentation or behaviour fix that keeps the contractpatch (1.0.1)A clarified description, a corrected example.
Breaking changemajor (2.0.0)Anything in the next list.

What counts as breaking

  • Removing or renaming an endpoint, an operationId, a response field or an enum value.
  • Changing a field's type, format or meaning, including how an amount is encoded.
  • Making an optional request field or a parameter required.
  • No longer guaranteeing a response field that was always present.
  • Removing a documented response status.
  • Changing the semantics of an existing error code.

Write clients that tolerate additions. Ignore response fields you do not know, keep a default branch for enum values and error codes you have not seen, and do not depend on the order of fields or of keys in an object.

How a breaking change ships

  1. The old behaviour stays served under the current major version for at least 12 months after the notice, and at least 6 months for an endpoint nobody called in the last 90 days.
  2. From the notice, the affected endpoints answer with Deprecation: true, a Sunset header carrying the removal date (RFC 8594) and a Link header with rel="deprecation" pointing to migration notes. The release notes and the dashboard carry the same date, and merchants whose keys called the endpoint in the last 30 days are emailed.
  3. The replacement is available before the notice starts.
  4. The old behaviour is removed on the Sunset date, and the new major version appears in API-Version.
A deprecated endpoint (example values)
Deprecation: true
Sunset: Wed, 30 Jun 2027 00:00:00 GMT
Link: <https://example.com/migrate>; rel="deprecation"

Security fixes can shorten this period. The notice then says why.

How we hold ourselves to it

A copy of the frozen 1.0.0 contract is kept in the repository and our test suite compares every change to the live contract against it. The build fails when an operation, a documented response, a schema property, an enum value or a guaranteed response field disappears, or when an existing operation gains a required parameter or field. The staff Admin API is internal, versioned separately, and carries no compatibility promise.