API Lifecycle

Our API has a single version that evolves over time instead of having multiple versions simultaneously. This allows us to introduce new features and improve functionality while maintaining a stable and reliable experience for our users. This section outlines how we manage changes to the API, including how we handle feature additions, deprecations, and communications.

Guiding Principles

Incremental Evolution: Instead of releasing entirely new versions of the API, we enhance the current version by adding new features and deprecating outdated ones.
Backward Compatibility: We strive to ensure that changes to the API do not break existing integrations.
Transparency: We are committed to keeping our users informed about API changes through clear and timely communication.

Understanding Breaking and Non-Breaking Changes

In the light of evolving our API, it’s critical to distinguish between breaking changes, which can disrupt existing integrations, and non-breaking changes, which enhance functionality without affecting current users.

Breaking Changes

Breaking changes alter the behavior of the API in a way that existing clients cannot function without modifications. These changes require users to update their integrations to maintain compatibility.

We consider the following types of changes to be breaking.

Removing or Renaming Endpoints

Removing an endpoint entirely.
Replacing an endpoint for an equivalent endpoint, e.g.;
- Changing its method from GET to POST;
- Changing the URL structure (e.g., /merchants/{id} to /accounts/{id}).

Modifying Request or Response Formats

Adding required fields to requests.
Removing required fields from requests or responses.
Renaming or deleting response fields.
Renaming or deleting required query parameters.
Changing the data type of a field (e.g., integer to string).

Modifying Authentication or Authorization Requirements

Introducing new mandatory authentication methods.
Changing access permissions for an existing endpoint.

Altering Error Codes

Removing or significantly changing error codes that clients rely on for handling errors.

Sometimes breaking changes are unavoidable. Read the next section on what our policy is around these types of changes.

Non-Breaking Changes

Non-breaking changes enhance the API in ways that do not require existing clients to update their integrations. These changes are backward-compatible and ensure that current workflows remain unaffected. You must be sure that your integration can handle these types of changes.

We consider the following types of changes to be non-breaking.

Adding New Endpoints

Introducing new endpoints that do not interfere with existing ones.

Adding Fields

Adding new optional fields to the request.
Adding new optional or required fields to the response.
Making previously required fields optional.

Change the Order

Changing the order of the JSON fields in the request or in the response.

Adding New Query Parameters

Adding new optional query parameters that are not required for existing functionality.

Adding New Error Codes

Introducing new error codes while retaining existing ones.

Improving Performance or Stability

Optimizing the backend to improve response times or reliability without altering the API’s contract.

Deprecation Policy

Occasionally, certain features may become obsolete and need to be deprecated. The removal of these features might mean your integration will break. That’s why we have a phased deprecation process in place, which follows these steps:

Announcement: Deprecations are announced in advance through our changelog and email notifications.
Deprecation Warnings: Deprecated features are marked with a tag that says DEPRECATED. Next to that, the removal date will also be specified.
Grace Period: We provide a sufficient grace period (typically 6 months) to allow clients to transition away from deprecated features.
Removal: Once the grace period ends, deprecated features are removed. If necessary, detailed migration guides are provided to assist users in adapting to alternatives.

Testing and Feedback

To ensure a smooth integration experience for our users we provide the following:

Experimental Features: New features may be released as experimental for early testing and feedback. Features that are experimental are marked with the EXPERIMENTAL tag. Please see the below section on The EXPERIMENTAL Tag for more information. We are currently in the process of transitioning from the old BETA tag to the new EXPERIMENTAL tag, please reach out if there is any confusion during this transition.
Sandbox Environment: Users can test their integration in a dedicated sandbox environment without production impact. Our sandbox environment is duplication of the entire production system where we simulate responses from upstream systems (such as issuers).
Feedback Channels: We encourage users to share their feedback on proposed changes via our support team.

EXPERIMENTAL Tag

We want our clients to test and help us shape and validate new features. To be able to do this we need to be able to release features that are considered experimental or still under development to sandbox and production. Functionality in this state is indicated with the EXPERIMENTAL tag on our API documentation.

When a feature has the EXPERIMENTAL tag, this could mean any of the following:

It could be changed in a breaking way without following the normal deprecation process.
It could be unstable.
It could have incomplete documentation.
More rarely, it could be removed entirely.

In case of breaking changes of an experimental feature, there will be appropriate communication towards clients using the feature in question. Given that experimental features do not follow the normal deprecation process, this communication is just for informational purposes only.

API Permissions are not marked explicitly as experimental. New permissions added to new experimental endpoints are inherently experimental. This is because they’re tightly coupled to the experimental endpoint and only exist there; their lifecycle is the same as the endpoint.

Over time, we assess the status of the feature. If applicable, we do this together with the clients piloting the feature. This includes but is not limited to:

Completeness of the feature;
Stability of the feature;
Documentation of the feature;
Adoption of the feature.

Once we conclude the feature is up to par with our quality standards, the EXPERIMENTAL tag will be removed. When EXPERIMENTAL gets removed from a feature, it will be documented in our release notes.

We recommend not using features that have the EXPERIMENTAL tag for production purposes unless there are very specific reasons to do so. Please consult with your Silverflow contact if you intent to integrate with experimental features for testing purposes.

Commitment to Stability

Our goal is to ensure a seamless experience for our users as the API evolves. By following this policy, we aim to balance innovation with stability, enabling you to build and maintain robust integrations with confidence.

For questions or concerns about our API evolution policy, please contact our support team or visit our developer portal for more information.