HTTP for API Transport
Resources and URI Structure
Representation Profiles and Schemas
Optimistic Locking and Concurrency
Error Responses and Error Representation
Apiture API License Agreement
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,
Apiture-Version request header.
Resource Profile Versions
Apiture Open Banking API versions are semantic versions, which is
a version string in the form of
major.minor.patch, such as
- 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
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
- 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:
- Add new paths and operations
- Add new optional properties, parameters, or enumeration values
- Redirect operation requests on resource URIs to other URIs
The term “parameter” is defined by the OpenAPI Specification and can refer to a query parameter or a header parameter. ↩
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