Skip to main content

​
Version in the path

The major version is part of every path: /provider/v1, /partner/v1. All surfaces start at v1. A new major version (v2) would run side by side with v1, with its own reference.

​
Changes without a new version

Within v1 AllRide only makes additive changes:
  • new operations, commands and query parameters;
  • new optional request properties;
  • new response properties and _links relations;
  • new enum values, error codes and error members;
  • new webhook types and payload properties;
  • relaxed validation (longer maximums, more accepted values).
Your integration must ignore unknown properties and handle unknown enum values and error codes. See Compatibility rules.

​
Breaking changes and new versions

These changes happen only in a new major version: removing or renaming an operation, property or parameter; making an optional input required or tightening validation; changing a type, format, unit or meaning; changing status codes or error codes of an existing outcome; changing envelopes, pagination defaults or id formats; adding a required permission to an existing operation. The published OpenAPI document is checked against these rules on every change.

​
Deprecation and sunset

A deprecated operation or major version answers every request with:
  • At least 12 months pass between a new major version becoming available and the old one’s sunset; at least 6 months for a single operation that has a v1 successor.
  • The reference marks deprecated operations.
  • Partners who still call a deprecated operation get emails at deprecation and 90, 30 and 7 days before sunset, sent to contacts.technicalEmail.
  • After the sunset, the operation answers 410 api-version-sunset (with more.sunsetAt and more.successorUrl) for 90 days, then 404.

​
Webhook versions

Webhook bodies carry no version. The body is always {"event": {"id", "type", "timestamp"}, "payload": {…}}, and a payload only gains fields: ignore properties you do not know. A breaking change to a payload ships as a new event type, which you subscribe to when you are ready; the existing type keeps its shape.

​
Staying informed

  • Keep contacts.technicalEmail on your partner a current, monitored mailbox: deprecation notices and security emails go there.
  • Watch for Deprecation and Sunset headers in your logs.