Versioning

We have designed Apiture Open Banking APIs with evolution in mind. We add new features to the APIs in new versioned releases, but Apiture Open Banking APIs do not include a version identifier in URIs. Resource URIs are durable addresses of domain objects (like accounts, documents, contacts, transfers), and the address of a resource should not change every time there is a new version of an API. Instead, to invoke a specific version of the API, include an Apiture-Version request header.

Apiture-Version Header

Resource Profile Versions

Semantic Versioning

Apiture Open Banking API versions are semantic versions, which is a version string in the form of major.minor.patch, such as 1.2.0 or 2.5.4.

  • Major version numbers are incremented if there is an incompatibility between versions of an API
  • Minor version numbers are incremented when new features are added
  • Patch version numbers are incremented when defects are fixed or when minor documentation or description text is changed

Each Apiture Open Banking API may evolve at a different rate from other APIs. For example, there may be two feature releases of the Accounts API, but no updates to the Transactions API. Thus, the most recent version of Accounts may be higher (such as 1.2.0) than the version of Transactions (such as 1.0.0).

Requests to Apiture Open Banking APIs require an API Key header parameter. (See Getting Started for authentication information). You get an API key (also known as a client ID) from the developer portal, and it is tied to a specific version of each Apiture Open Banking API.

When you develop your client against version 1.0.0 of the Accounts API and use an API key issued for Accounts 1.0.0, your API requests go to version 1.0.0 Accounts API. Apiture or financial institutions can choose to upgrade older versions and replace them with newer versions. If this happens (for example, a financial institutions replaces version 1.0.0 of the Accounts API with version 1.2.0, then we route requests with either an API Key attached to Accounts 1.0.0 or an explicit Apiture-Version header to the Accounts 1.2.0 API.

API Evolution Rules

We abide by the following API evolution and backwards compatibility rules for minor and patch version changes.

  • We may add optional properties or non-required parameters

We do not:

  • Remove Operations
  • Change the fundamental behavior of an operation
  • Change OpenAPI operationId names
  • Change the type of a property or parameter1
  • Delete a property2 or parameter
  • Make optional properties or parameters required
  • Remove enumeration values
  • Strengthen validation constraints (for example, adding minimum/maximum values constraints on numbers or array sizes)

We built the Apiture Software Development Kits for specific API versions. For example, there are separate SDKs for Accounts 1.0.0, Accounts 1.1.0, and Accounts 1.2.0. The version-specific SDK passes the Apiture-Version header on requests unless the SDK is configured to use the inferred version.

See also the round-trip problem about getting API clients built for one API version to work with a newer API service.

Examples of compatible changes

The following are examples of non-breaking changes to our APIs:

We may:

  • Add new paths and operations
  • Add new optional properties, parameters, or enumeration values
  • Redirect operation requests on resource URIs to other URIs

  1. The term “parameter” is defined by the OpenAPI Specification and can refer to a query parameter or a header parameter. ↩

  2. A property is a property within a model schema - most notably, a named value in a JSON request or response body. Properties have a type and may have constraints such as minimum, maximum. ↩