Skip to content
Ubhub Location Service
Versioning

Guides

Versioning

The version is part of the URL. Within a version, your integration keeps working.

Versions

The current version is v1, and every endpoint lives under /v1/. A new major version, such as /v2/, is introduced only when a breaking change is unavoidable. The two versions then run side by side so you can migrate at your own pace.

Compatible changes

These can happen within v1 at any time, without notice:

  • New endpoints.
  • New optional query parameters.
  • New fields in response objects.
  • New values in open-ended fields, such as a new place type or a new details entry on an error.
  • New travel modes.
  • Better results from the same request, for example after the underlying data is updated.
  • Changes to error message text (branch on code, never on the message).

Build tolerant clients

Ignore response fields you do not know, and do not fail on unknown values of open-ended fields such as type.

Breaking changes

These never happen within v1:

  • Removing or renaming an endpoint, parameter or response field.
  • Changing the type or meaning of an existing field.
  • Making an optional parameter required, or tightening its accepted values.
  • Changing the error envelope or removing an error code.
  • Changing authentication.

Deprecation

When a new major version ships, the previous one stays available for a published transition period. Deprecated versions are announced in this documentation before they are retired, with a migration guide covering every change.