Developers / Versioning

Versioning and deprecation

The version is in the URL. This page is the commitment you can build against.

What will not break your integration

These are additive and ship on /v1 without notice:

  • New endpoints.
  • New optional request parameters.
  • New fields in a response, including new sections inside report.
  • New values in pendingSections or sectionStatus.
  • New error code values, announced in the changelog beforehand.
Your client must ignore fields it does not recognise. Vehicle data grows and we add sections as we get access to them. A client that rejects unknown fields, or that deserialises strictly into a fixed structure, will break on a routine release. That is the one obligation this policy puts on you, and it is the reason we can improve the data without forcing a migration on everyone.

Likewise, branch on error code with a sensible default for values you have not seen.

What gets a new version

A change that could break a working integration goes to /v2:

  • Removing or renaming a field.
  • Changing the type or the meaning of a field.
  • Changing authentication.
  • Changing which status code a situation returns.
  • Changing what is billable.
  • Adding a required request parameter.

Deprecation

When something is deprecated:

  • It is announced in the changelog and emailed to your contact address.
  • Responses carry Deprecation: true, a Sunset date and a Link to the changelog entry.
  • At least 6 months pass between that announcement and removal.

When a new major version ships, the previous one keeps working for at least 12 months. We will not remove a /v1 endpoint without those headers appearing first. If you see a Sunset header you have at least half a year, but do not ignore it.

The API description

The machine readable description is published at https://api.mrvin.com/v1/openapi and always reflects what is deployed. It is generated from the running service rather than maintained separately, so it cannot drift from actual behaviour.

Generate clients from it if that suits you, but keep your generator set to ignore unknown fields.