Console

Versioning

Our approach to API versioning and standards.

Suggest Edits

Starting with the Payments API v3, we are introducing API standards to our endpoints. Standards play a big role in determining URI schemes and the future of versioning at TrueLayer.

Standards

API standards define the structure of:

  • requests
  • responses
  • status codes
  • errors
  • general API behaviour

We use standards to determine a URI path for our endpoints. The latest iteration of our API standards is v3. New product releases will follow v3 standards, and their endpoints will have this prefix.

For example, to create a payment with the Payments API, send a POST request to:

https://api.truelayer.com/v3/payments

Legacy products will continue to use the existing URI structure — we aren't making any changes to these. See our API references for a full list of all of our endpoints.

📘

Minor versioning

In the future, we plan to introduce a new minor versioning system. This will allow developers to have more control over which new features they want to opt in, and avoid being subjected to any breaking changes. Furthermore, we will be able to launch new changes to our APIs without disruption for developers.

Non-breaking and breaking changes

At the moment, we do not introduce any updates to our APIs that cause breaking changes.

Non-breaking changes

We consider the following changes to be non-breaking:

  • Adding a new endpoint
  • Adding a new field to a request body
  • Adding a new field to a response body
  • Changing a field in a request body from required to optional, without a behavioural change
  • Changing a field in a response body from optional to required
  • Adding a request or response header entry
  • Changing a request header entry from required to optional
  • Changing a response header entry from optional to required
  • Changing the value of a header
  • Changing a response error message
  • Adding a new response status code

Breaking changes

We consider the following changes to be breaking:

  • Adding a required field to a request body
  • Renaming a field in a request body
  • Removing a field from a request body
  • Removing a field from a response body
  • Changing a field in a response body from required to optional
  • Removing a request header
  • Removing a required response header
  • Adding a required request header
  • Changing a response header from required to optional
  • Changing the type of a field in a request or response body
  • Changing the behaviour of the API in a way that requires you to change your integration

Compatibility with previous major versions

We do not recommend mixing functionality from different major versions of our API (e.g. Payments API v2 and Payments API v3), as they are not explicitly designed to be interoperable.

Client libraries

Our client SDK libraries are generally kept up-to-date with the latest changes to our API.

While there can be some delay incorporating non-breaking changes, we aim to always release corresponding client library updates alongside breaking API changes.

Updated 10 months ago

Next steps