Versioning
How the /v2 contract changes, and how to write a client that keeps working.
The contract version
Every /v2 response has the header X-QDP-Contract: 2.0. GET /v2/info repeats it as contract_version.
Minor versions only add fields. So a client keeps working if it does two things:
- Ignores any response field it doesn't know, and doesn't fail on one.
- Sends only documented fields, because requests are strict: unknown fields return
400 invalid_request.
What the version doesn't promise
/v2 promises the same shape, not the same answers. Routes, ETAs and geocoding results change when the map data is updated, and they depend on the engines behind the API. Don't hard-code a specific result in a test. Check the shape and that the value is sensible.
Contract files
The schemas are published at /docs/schemas/, and the API is described in /docs/openapi.json.
v1
The older endpoints still work and haven't changed. New clients should use /v2. See v1 endpoints.