Versioning

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.

Semantic Versioning

Apiture Digital 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 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.

Schema Versions

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:

    group
    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 account schema, etc.

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 parameter¹
• Delete a property² 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:

We may:

• 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 requirements

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.