Versioning

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.

Apiture-Version Header

Resource Profile Versions

Semantic Versioning

Apiture API versions are semantic version, 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 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
  • OpenAPI operationId names 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

  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