Versioning
The API version is in the path: /api/journeys/v1.
What can change within v1
Changes within v1 are additive:
- new endpoints;
- new optional request fields;
- new response fields;
- new enum values in responses;
- new error codes.
Write clients that ignore response fields they do not know, and that treat an unknown error code by its HTTP status.
A breaking change (removing or renaming a field, making an optional field required, removing an enum value, changing a type) is published under a new path version. The previous version stays available alongside it for at least two releases.
How the contract is guarded
The service keeps a contract snapshot: every route it registers and the JSON Schema of every request contract. A test fails when the snapshot and the code disagree, and the snapshot diff tells an additive change from a breaking one. This documentation and the OpenAPI document are generated from that snapshot; the reference states the source commit it was built from.
Deprecation and Sunset response headers are not sent today; deprecations are announced in release notes. There is no public changelog feed yet. See Availability.
Field naming
The quote store and repricing surfaces use snake_case field names (customer_ref, booking_ref). The order orchestration, order operations and group surfaces use camelCase (customerRef, tripId). Each surface is consistent within itself; the difference is kept for compatibility within v1.