API versioning and backward compatibility

Overview

At Akkuro Lending, we use versioning to evolve our APIs with each release over time. Once published, an API version is considered stable and remains unchanged. To accommodate breaking changes while maintaining backward compatibility, we introduce new versions and continue supporting older ones for a defined period.

Akkuro Lending APIs use header-based versioning. Clients can indicate the version in the HTTP Accept header.

To see all available API versions, refer to the API schemas.

API version format

The version format follows the Calendar Versioning scheme with a YYYY.Major.Minor format.

Part	Description
`YYYY`	The year of release.
`Major`	A number incremented for releases with major features or changes.
`Minor`	A number incremented for minor enhancements, bug fixes, or patches.

For example:

2025.1.0: First big release in 2025.
2025.2.0: Another major update later in the same year.
2025.2.1: A small change or fix after the second big release.
2025.2.2: A subsequent fix or improvement after the second major release.

Make requests to an API version

Multiple API versions are supported in parallel. The API Schemas will reflect all available API versions. You can use any version that has not yet reached its end-of-life date. To check version support timelines, refer to Deprecation of APIs.

When a client sends a request with a specific version header, the server reads the version from the header and uses the corresponding API version to process the request.

Request

You need to specify the API version in the HTTP Accept header.

Accept: application/json;api-version=2025.1.0

Caution

We recommend that you specify the API version in every request to prevent unexpected behavior. If your request doesn't include a version, the API defaults to the latest supported version, which may result in unexpected breaking changes, such as changes to response formats or data structures. Your application should continue using the API version that it is currently stable with, for as long as that version is supported.

Request example:

curl -i https://api.lending.akkuro.io/counterparty-management/counterparties \
-H "Accept: application/json;api-version=2025.1.0" \
-H "Authorization: Bearer YOUR_JWT_HERE"

Response

You can make API requests and have the server respond with the following metadata in the header response:

Content-Type: Indicates the actual version of the API that served the response.
X-API-Id: Indicates a unique identifier of the API. This identifier remains unchanged across versions — it's tied to the API itself, not a specific version.
X-Supported-Versions: Lists all versions of the API currently supported by the server. Each version is separated by a comma.

Header response example:

HTTP/1.1 200 OK
Content-Type: application/json; api-version=2025.1.0
X-API-Id: 22cd7741-ala8-4003-9987-e92d75056119
X-Supported-Versions: 2025.2.0, 2025.1.0, 2024.3.0

Deprecation of API versions

The x-eol-date field indicates the end-of-life (EOL) date for the API version. After this date, the version is no longer supported and will be removed, so you should plan your upgrades in advance.

You can find the x-eol-date field in the specification of an API version. For example:

x-eol-date: '2025-02-28'

The end-of-life date format is YYYY-MM-DD. In this example, the version will no longer be supported after February 28, 2025.

To learn how to check an API version’s end-of-life date in the API schema, see the following topic: Use API schema browser.

If you use a deprecated version in the request, then the server returns an error like the following:

{
    "title": "Unsupported API version",
    "status": 406,
    "detail": "The HTTP resource that matches the request URI '' does not support the API version '2022.1.0'.",
}

Overview​

API version format​

Make requests to an API version​

Request​

Response​

Deprecation of API versions​

See also​