API Lifecycle

The API lifecycle represents a set of information about the API’s maturity levels, versions, events, and backward compatibility.

API Maturity Levels

Finastra has defined four levels of maturity depending on the API release status:

DRAFT - APIs are published to FusionCreator to let you know what Finastra is committed to delivering in the coming future. The APIs are in a very early stage. The objective of this status is to collect feedback from the fintech community.
BETA – APIs offer a first implementation of Finastra’s core systems. They act as a preview where you could test our API and collect/offer feedback on the integration.
GA – APIs designated as Generally Available (GA) are stable, no breaking changes are allowed.
DEPRECATED – APIs are no longer recommended for use. Before deprecation, a removal notice period and the effective date are communicated on FusionFabric.cloud Community.

Maturity levels are displayed in several places:

In the API Catalog – on each API card.

API Catalog

If no maturity is displayed, the API is GA and can be used in production.

On the API reference documentation page, after selecting an API card from the API Catalog.

API Reference Documentation

In the OpenAPI specification, as the x-finastra-maturity-level custom field.

API Swagger

"info": {
  "version": "1.0.0",
  "title": "Happy Banking",
  "description": "This is a sample API.",
  "x-finastra-short-description": "Action of the API.",
  "x-finastra-category": "Consumer Banking",
  "x-finastra-subcategory": "Account Operations",
  "x-finastra-tags": [
    "Banking"
  ],
  "x-finastra-channel-type": "B2B",
  "x-finastra-maturity-level": "BETA",
  ...
}

For each maturity level, there are major lifecycle events that could be applied, depending on the use case.

API Lifecycle Events

The following table lists the APIs lifecycle events:

No.	Lifecycle Event
1	Announcement of a new DRAFT API
2	(Optional) Introduction of breaking changes to a DRAFT API
3	Promotion of an API from DRAFT to BETA
4	(Optional) Introduction of breaking changes to a BETA API with a notice period
5	Promotion of an API from BETA to GA
6	Introduction of a new feature with non-breaking changes to a GA API
7	Introduction of a new version in BETA ( `v1` and `v2` coexist)
8	Promotion of an API from GA to DEPRECATED
9	Announcement of the planned removal date of an API (can be done during phase 8)
10	Removal of an API

Breaking Changes

Changes to an API that could break your client application are called breaking changes. If you consume an API with a breaking change, such as an updated structure, or an endpoint that was deleted, your app could stop functioning properly.

As a guideline, the introduction of breaking changes into an API is governed by rules such as:

It CAN be done for DRAFT and BETA APIs.
It MUST NOT be done to GA APIs - the introduction of breaking changes to a GA API at version 1.0.0 MUST result in a new version of said API.

API Version

An API represents a contract between the provider of a service - FusionFabric.cloud, and the consumer of a service - you, the fintech. This contract can evolve over time and each publication of an API by a provider has an associated version number.

FusionFabric.cloud APIs use the semver.org semantic version specification whereby the version of an API is represented by a major number, a minor number, and a patch number.

FusionFabric.cloud API versions are based on the following rules:

Major version – this version number changes when the API updates impose a major contract change that requires action from you to make your app compatible with a new version. It usually involves breaking changes to the API.

For example, the increment of the major version, v1, in the URL path of the API in https://api.fusionfabric.cloud/retail/v1/accounts.

Minor version – this version number changes when an API update is published that does not require action from you to make your app compatible with a new version. For example, if there are changes in the documentation.
Patch version – this version number changes when an API update does not alter the API contract.

Examples of breaking changes to an API, that result in a change to the major version number:

removal of a path
removal of an operation
removal of a property used in a request or response
change of a property from optional to required, in a request
change of a property from required to optional in a response

Examples of non-breaking changes or minor changes that would not make an existing API incompatible with your app:

addition of a method
change of a property from required to optional in a request body
change of a property from optional to required in a response body

The following table shows the evolution of an API that follows Finastra’s approach to semantic versioning:

Example URL	API Version	Reason for API version change
`/v1/accounts`	1.0.0	Initial version of the API.
`/v1/accounts`	1.0.1	Documentation updated.
`/v1/accounts`	1.1.0	An optional field and new endpoints added.
`/v2/accounts`	2.0.0	Breaking change by the introduction of a new major feature to the API.

Backward Compatibility

Finastra has a policy in place to ensure backward compatibility for client API calls.

Backward compatibility means that an API and its underlying server implementation provides the same capabilities as previous versions of that API. When you start using an API at a particular version, the capabilities of the API remains available within the same major version, without the need to upgrade your app.

The implication of this policy is that FusionFabric.cloud APIs cannot be presumed to be compatible with all server versions. Backward compatibility does not apply to breaking changes of an API that are introduced by the major versions - changes from 1 to 2 are not backward compatible.

App Lifecycle

In the context of FusionFabric.cloud, an app/application means:

An artifact that defines a set of APIs and their credentials.
An artifact published on FusionStore, containing additional metadata information, such as marketing content.

Application Maturity Level on FusionStore

The following statuses apply to the applications in the FusionStore:

Coming Soon - app undergoing the validation process. The app card is available in the FusionStore to generate demand. Legal checks are completed at this point.

Coming Soon

In Store - app that is published and tracks opportunities for sale on FusionStore . The whole documentation for sales enablement is completed. Initial risk and compliance checks are completed.
In Market - app that has been through all the validation stages. The app can be sold via FusionStore. The security assessment and final due diligence are completed.

App and API Compatibility

An app consumes APIs. Therefore, the app maturity level is related to API maturity level as follows:

API/APP	Coming Soon	In Store	In Market
Not Available	YES	NO	NO
Draft	YES	NO	NO
Beta	YES	YES	NO
GA	YES	YES	YES
Deprecated	NO	NO	YES

For example, an app that has In Store status, must rely on Beta or GA APIs. It cannot consume Draft or Deprecated APIs.