This document explains how Flowroute versions its Public APIs, what we consider a breaking change, and how we decide whether to do a minor or major version bump. The audience of this is intended to be both Flowroute customers developing against our APIs and internal stakeholders for our APIs.
The Flowroute API utilizes both major and minor versions in order to maintain dependable API contracts with its users. This versioning is denoted as MAJOR.MINOR; e.g., v2.1 would be major version two minor version one, so the first minor version of the second major version.
- Breaking Changes
- Continuity (Non-Breaking) Changes
- Major Version Bump
- Minor Version Bump
- Versioning Resources vs. APIs
- Support and Deprecation
Breaking Changes
A breaking change is defined as any change that would require a user to update their application in order to continue working with the API as originally intended. If an API method or object attribute is removed or renamed, then a breaking change has taken place. For example, if we have attributes named “primary_route” and “failover_route” on the second major version of our Numbers object, but we later rename those attributes to “voice_primary_route” and “voice_failover_route”, then a breaking change has taken place. As such, we would need to bump the API version in order to prevent breaking existing customer integrations.
Continuity (Non-Breaking) Changes
Flowroute reserves the right to make additive changes to the API without a version bump or notification to the customer. We may add new resources, methods, attributes, and relationships to the API and these will not be considered breaking changes. For example, if we add a new relationship to the Numbers object for a “message_primary_route”, we will neither bump the API version nor notify our customers before launching the update. This applies to both the standard APIs (client-generated requests) as well as the Push APIs (server-generated requests; inbound SMS POSTs). As such, users should design their applications to be flexible enough to not break when new fields and methods are added to resources.
Major Version Bump
Flowroute utilizes major API version bumps whenever we make significant changes to the overall structure of the API itself. For example, a change in the authentication method or overall JSON design would result in a major version bump. Flowroute’s v2 API utilizes Basic Auth for authentication and all API requests/responses are JSON-API compliant. Changing either of those things would require a major version bump since the nature of the API itself would be different.
Minor Version Bump
Minor version bumps are used when making breaking changes on a resource level without changing the overall structure of the API. For example, renaming the Numbers object’s “primary_route” relationship to “voice_primary_route” would be a breaking change, but a minor one. As such, Flowroute will version the API and publish a new version of the API and its relevant documentation. For APIs, Flowroute will attempt to minimize the use of minor version bumps.
Versioning Resources vs. APIs
The Flowroute APIs are versioned at an API level rather than on a resource level. For example, Flowroute API v2 contains resources for Numbers, Routes, and Messages. If a breaking change is made to Numbers, but not to Messages, the entire API will be version bumped. After the version bump, users would interact with API v2.1 and are able to access the new Numbers resource as well as the unchanged Messages and Routes resources. We implemented our versioning strategy in this way in order to be able to isolate the API contract versions between resources as well as for individual resources. Fracturing the version numbers on a per resource level would require much greater development efforts on the part of users in order to build applications compatible with multiple versions of objects rather than just working with API versions.
Support and Deprecation
Flowroute will support the current and prior version of major APIs and any underlying minor versions. As new APIs move into GA, Flowroute will have have a targeted campaign to move customers to the new API (or the prior version) and actively schedule the end of support for the minus 2 version, which typically will occur 6 months after announcement. For example, when Flowroute releases API v3 and begin the sunset of v1 including any v1 minor releases approximately 6 months later. However, version support should generally last for a period of no less than 2 years to minimize churn for developers. API deprecation will be accompanied by extensive communication programs associated with the launch of the new API to give developers time and support to make changes. Whenever possible, Flowroute will maximize backwards compatibility for its customers.