Guides

API Versioning

To help ensure that your API integration functions smoothly and without interruption, Branch has developed policies defining what are breaking and non-breaking changes and how we inform our customers of any changes.

This page contains an explanation of the policies and provides links to our changelog, which lists any changes to the API.

Versioning

To prevent breaking changes disrupting your integrations, Branch issues our APIs in a series of versions (v1, v2), and build numbers. Any breaking changes will be introduced as part of a new version. New builds of a version will not include any breaking changes.

When Branch releases a new version we will post a notification on the changelog and provide documentation describing how to use the new version.

Breaking Changes

A breaking change is a change in a new version that is not backwards-compatible with an older version and might disrupt your existing API integration. Breaking changes include the following:

  • Removing an endpoint.

  • Adding a required parameter.

  • Removing or renaming a parameter.

  • Removing a request field or response field.

  • Changing the type for a parameter or a response field.

  • Changing or removing enum values.

Non-Breaking Changes

A non-breaking change might add functionality or options in making API calls but will not cause your existing calls to malfunction. Non-breaking changes include the following:

  • Adding an optional parameter to an existing endpoint.

  • Changing a parameter from required to optional.

  • Adding additional fields and values to request parameters, responses, and reason code enums.

  • Adding new properties or changing the order of properties in API responses.

Branch will post release notes in our changelog notifying you of both breaking and non-breaking changes. An RSS feed is available here, so you can subscribe using your RSS reader and be notified of any updates.

Specifying an API Version

Branch API versions are indicated in the endpoint URL. For example, this points to a v1 endpoint:

https://api.branchapp.com/v1/organizations/{orgId}/employees/{employeeId}/wallets

To change to a new API version you should read the changelog and other documentation. You can also consult with your Branch CS representative to help you make any changes to your integration needed before using the new version, and should run tests on your modified integration using the Branch API sandbox.

Updated 4 months ago