Guides

REST API and Webhook Breaking Change Policy

Suggest Edits

At BR-DGE, we understand the importance of stable integrations for our partners. This policy details our approach to managing breaking changes across our REST API and Webhooks of our Payment Orchestration Platform. We are committed to minimising disruption while continuously enhancing our platform.

Breaking Change

A modification to any API that requires changes to pre-existing integrations to maintain functionality. Examples include, but are not limited to:

  • Changing the authentication or authorization mechanisms in a way that invalidates existing authentication methods
  • Changing the request or response format in a way that breaks existing integrations (e.g., changing data types of existing fields, making previously optional fields required, removing existing fields).
  • REST API:
    • Removal or renaming of an API endpoint.
    • Changing HTTP status codes for existing error conditions in a way that existing clients are not prepared to handle.
  • Webhook:
    • Changing the HTTP method used for an existing webhook.
    • Changing the HTTP response code that client must return to acknowledge receipt of an existing webhook.
    • Changing the mechanism for verifying the authenticity of BR-DGE webhook notifications.

Non-Breaking Change

A modification that does not require changes in client code or integration logic. Examples include but are not limited
to:

  • Adding new optional parameters or fields if existing functionality is not affected.
  • Adding new enum values, error codes or HTTP statuses if existing functionality is not affected.
  • Reordering fields.
  • Improving performance or security without changing the API contract.
  • Relaxing field validation rules.
  • Adding new REST API endpoints if existing functionality is not affected.
  • Adding new webhooks if existing functionality is not affected.
  • Deprecating Feature/API Element: A feature or API element (endpoint, field, webhook, etc.) that is scheduled for removal in a future release, but is still supported.

⚠️

We cannot guarantee zero code changes from OpenAPI spec updates that are ran through code generators. However, we will maintain compatibility for pre-existing integrations.

Policy Principles

  • Backward Compatibility: We strive to maintain backward compatibility. Non-breaking changes are preferred over breaking changes.
  • Versioning: We use versioning to manage breaking changes across all API types. This may manifest differently depending on the API (e.g., API versioning for REST, identifiers for Webhooks)
  • Deprecation Period: Before removing support for any feature or API version, we will provide a deprecation period as described in our deprecation process.
  • Communication: We will communicate breaking changes and deprecations clearly and proactively through all communication channels.

Versioning Strategies

We employ versioning strategies tailored to each API type:

  • REST API: Major versioning only (vX). Breaking changes will result in a new major version. Minor and patch versions are not used for REST APIs.
  • Webhooks: No versioning, but new webhooks will be defined in the event of breaking changes.

Deprecation Process

  1. Announcement: We will communicate breaking changes and deprecations clearly and proactively through all communication channels. Announcements will include:
    • The specific feature, API element or API version being deprecated.
    • The reason for deprecation.
    • Alternative solutions or migration paths.
    • A warning that the feature and/or API element will be removed in future versions of the feature and/or API.
  2. Deprecation Warnings: Deprecated features or API elements may trigger deprecation warnings (e.g., in response headers, console logs, or as part of API messages such as API responses or webhook payloads). BR-DGE will also monitor usage of deprecated features where possible.
  3. Removal: Following the deprecation period, older features or API versions will be retired. We will proactively inform and assist any affected merchants and partners with a final notice before the removal.

Communication Channels

We will use the following channels to communicate API changes:

  • Developer Docs: Our developer docs will be the central hub for API information, including documentation, changelogs, and announcements.
  • Changelog: Each release will include a detailed changelog outlining all API changes.
  • Email Notifications: Email notifications regarding significant API changes and deprecations will be sent to registered merchants and partner stakeholders (both technical and business contacts).

Example Deprecation Announcements

  • REST
    • "The /payments/legacy endpoint is now deprecated and will be removed in a future version of the API. Please migrate to /payments/new. Please see documentation for the new endpoint"
    • “Version 1 of the BR-DGE REST API is now deprecated and support will be removed in Q3 2040. Please migrate to version 2.”
  • Webhook: "The oldEvent webhook notification is now deprecated and will stop being generated in Q4 2060. Please migrate to newEvent. See the updated event webhook documentation."

Exceptions

In rare cases, such as critical security vulnerabilities, legal requirements, or critical bugs, we may need to make breaking changes with a shorter notice period. In such situations, we will make every effort to minimise disruption and communicate the changes as quickly as possible.

Changes to this policy

This policy is subject to change at our discretion. We will notify Merchant/Partner business and technical stakeholders of any significant changes to this policy.

Updated 1 day ago