We have designed Apiture Digital Banking APIs with evolution in mind. We add new features to the APIs in new versioned releases, but Apiture Digital 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 does not change every time there is a new version of an API.
Apiture Digital 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 Digital 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).
Most requests to Apiture Digital Banking APIs require an API Key header parameter. (See Getting Started for authentication information). You get an API key from the developer portal, and it is tied to a specific version of each Apiture Digital Banking API.
The named schemas used for request and response bodies and nested data within these values are defined with a schema version. Schema versions do not track the API version because an API may change but the schemas in the API may not. The schema version tracks the changes to the schema.
The schema version is documented in the API reference which shows the version number in parentheses after the schema name and title:
Text Group (v1.2.0)
These numbers also follow the above Semantic Versioning rules.
Some schemas may not change within an API release
For example, if version 1.5.0 of an API adds a new operation
not in version 1.4.0, but the schemas have not changes, then the schema
version numbers also do not change. If one schema version changes
(for example, a new property is added to it), its version changes accordingly
(for example, the minor version number is incremented) but unrelated
schema version numbers do not change.
Additionally, some schemas are shared across multiple APIs,
such as the
collection schema, the
user schema, the
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)
Note however that major version number / breaking changes rules do not apply to pre-production (0.x.y) API versions. breaking changes can be introduced between 0.x and 0.x+1 releases.
See also [Release Notes])(../release_notes) for changes between releases.
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
- Return additional 2xx, 3xx, 4xx or 5xx response codes
Client applications which consume the Apiture Digital Banking APIs should follow these rules:
- Do not use strict JSON schema validation. For example, if you marshal a JSON response to a data structure in your client programming languages, this step should not throw an error if the JSON contains additional properties not defined in the JSON schemas defined in the API reference. Thus, if the client is coding against version 1.4.0 of an API and in version 1.5.0 Apiture Digital Banking APIs adds a new property to a schema, the client should accept that data.
- Clients should be prepared for an API operation to return any valid HTTP response code, even of that response code is not explicitly listed in the API reference or API definition document. A new version of an API may now return 202 Accepted response to the existing 200 OK response.
- HTTP response codes for the same operation may change between API versions when a different response code is more correct or accurate. For example, if version 1.4 returned a 400 response code for a specific API request, version 1.5 may return a more specific 422 response code instead. Or, an API may return 403 instead if that increases API security by not revealing information the caller should not have. In other words, the specific API response codes are not part of the API contract but are informative. However, Apiture Digital Banking APIs strive to always use the correct HTTP response code. That is, new releases of the the APIs do not change a 404 to a 412 response code when the underlying error is that a resource is not found.
The term “parameter” is defined by the OpenAPI Specification and can refer to a query parameter, a path parameter, or a header parameter. ↩
A property is an element within a model JSON schema
propertiesdefinition - most notably, a named value in a JSON request or response body. Properties have a name and type and may have constraints such as