HTTP for API Transport
Resources and URI Structure
Hypermedia Application Language (HAL)
Representation Profiles and Schemas
Optimistic Locking and Concurrency
Error Responses and Error Representation
Apiture APIs are designed with evolution in mind.
New features are added to the APIs in new versioned releases.
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.
Thus, Apiture APIs do not include a version identifier in the
URIs. Instead, requests may include an
Apiture-Version header in the request
to identify a specific API version of thr API that the client wishes to invoke.
Resource Profile Versions
Apiture API versions are semantic version, 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 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 APIs require an API Key header parameter. (See Getting Started for more information about authenticating to Apiture APIs). An API key (also known as a client ID) is obtained on the developer portal is tied to specific versions of each Apiture API. The API Key is may be thought of as a surrogate for the specific API version for each API.
Clients developed against version 1.0.0 of the Accounts API, using an API key that was
issued for Accounts 1.0.0, will be serviced by the 1.0.0 version of the Accounts API,
if it is deployed. Apiture or financial institutions may undeploy 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 requests with either an API Key
attached to Accounts 1.0.0 or an explicit
Apiture-Version header, will be routed to the
Accounts 1.2.0 API.
API Evolution Rules
Below are the rules for API evolution and backwards compatibility for minor and patch version changes:
- Operations may not be removed
- The type of a property or parameter1 cannot change
- A property2 or parameter may not be removed
- Properties or parameters that were optional cannot be changed to required
- New properties or parameters may not be required
- Validation constraints must not be strengthened (for example, adding minimum/maximum values constraints on numbers or array sizes)
- Enumeration values may not be removed
- Fundamental behavior of an operation may not change
operationIdnames may not be changed
The Apiture Software Development Kits are built for specific API versions. For example, there is be separate SDK for Accounts 1.0.0, Accounts 1.1.0, and Accounts 1.2.0. The version-specific SDK will pass the
Apiture-Version header on requests unless the SDK is configured to use the inferred version.
See also the round-trip problem about API versions and clients which are build for one API version working with an API service that is newer.
Examples of compatible changes:
- New paths and operations may be added
- New optional properties or parameters or enumeration values may be added. However, see also Client Considerations below.
- Operation requests on resource URIs may redirect 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