Skip to main content

API Versioning

We want you to be confident that your Fleetio API integration will continue to work even as we make changes to our API. In order to do this, we maintain multiple versions of our API endpoints. This allows us to make breaking changes without breaking your integration. Allowing you to upgrade to the latest version of our API at your own pace.

Endpoint Versions

Each API endpoint has a version number at the beginning of the path. For example, here is the endpoint for creating a new Service Entry.

POST /v2/service_entries

The version number is the first segment of the path, so this is Version 2 of this endpoint.

There is also a version 1 of this endpoint, which can be reached at:

POST /v1/service_entries

Deprecated Versions

Old versions of the API are usually deprecated. This means that we do not recommend using them for new development, but we will continue to support them for the foreseeable future.

Versioning Strategy

There are many ways in which an API endpoint might change, but we will not introduce a new version for every change. We will only introduce a new version when we make a change that is not backwards-compatible.

tip

If a change would break existing integrations, we will introduce a new version.

Breaking Changes and Backwards Compatibility

The following table includes examples of the types of changes we might make to an endpoint and whether we consider those changes to be backwards-compatible.

Breaking ChangesBackwards-Compatible Changes
New Version Required
  • Yes

    We will introduce a new API version when we make changes like this.

  • No

    We will not introduce a new version for changes like this.

Examples
  • Removing properties from an endpoint's response payload.
  • Adding a new required parameter to an endpoint's request payload.
  • Changing the type or meaning of a property in an endpoint's response payload.
  • Adding new properties to an endpoint's response payload.
  • Adding new optional parameters to an endpoint's request payload.
  • Changing the order of properties in an endpoint's response payload.
  • Changing the length or format of opaque strings or numbers. This could include things like IDs, error messages, labels, and other human-readable strings.
  • Adding new types of webhook events. Your webhook integration should expect to
  • see unfamilar event types.