In today’s fast-moving world, software platforms are in a constant state of evolution, and their associated Application Programming Interfaces (APIs) must move along in lock step. Changes and updates often include the launch of new features, in addition to squashed bugs, performance improvements, and security enhancements. As such, it is essential for API providers and consumers to ensure they’re both following best practices related to API updates.

At Recurly, we are positioned as both an API provider and consumer. Our API offering is critical to the success of our customers and partners as it provides the primary entry point into our industry leading subscription management platform. We take pride in providing our API in a way that empowers our customers to integrate quickly, while also minimizing friction and providing a top-notch development experience along the way. Recurly also consumes APIs from several leading SaaS companies in order to power tangential value that enhances our core offerings.

Drawing from our experiences at Recurly, we’ll discuss the advantages afforded to API consumers who implement continuous API upgrades and what API providers can do to help facilitate.

Let’s start with the advantages that should motivate API consumers to stay up-to-date with the latest iteration of an API:

  • Minimize the overall level of effort and risk to upgrade Generally, it’s much easier to deploy small, incremental changes over time rather than attempting to implement many changes all at once. Being forced to jump through several major iterations of an API while addressing a long punch list of potentially breaking changes can be time-consuming and risky as it’s more difficult to assess all of the various dependencies and potentially adverse effects. While API providers should do everything possible to minimize breaking changes, they are sometimes necessary when making improvements to the API.

  • Gain access to new features as soon as possible Waiting to utilize a new feature comes at an opportunity cost. Every day that a new feature lies dormant is a day lost in the realization of incremental business value. Even without an immediate business case for utilizing a new feature, it’s better to lay the groundwork proactively in order to minimize future impediments to business goals when the time comes to move forward quickly.

  • Take advantage of performance gains early Similar to the adoption of new features, delaying an API upgrade can often mean losing out on the opportunity to benefit from performance increases. Particularly in the world of e-commerce, every second of latency can mean the difference between hitting a conversion goal or losing a customer.

  • Stay on top of bug fixes and security patches While it is only responsible for API providers to support bug fixes and security patches with the same level of urgency across all supported iterations of an API, upgrading to the newest release is a self-empowering step that API consumers can leverage to ensure that they are on the most-supported version.   

While the advantages related to upgrades are undeniable, there are many reasons why an API consumer may be apprehensive of moving forward, chief among these being the fear of breaking changes and/or the level of effort required to upgrade. As such, API providers should make a good faith effort to ensure their interfaces are backward-compatible in order to reduce the effort and risk required for API consumers to take advantage of the newest versions of the API.

There are several steps that API providers can take to ensure that their updates do not cause unintended side effects or breaking changes. Here is a non-exhaustive list for illustration purposes based on some of our practices at Recurly:

  • Add but don’t remove Removing an aspect of the API or associated client library on which an API consumer has come to depend is a clear recipe for breakage. On the other hand, making optional additions to data structures or method signatures should enable the consumer to safely ignore the change and maintain business as usual until such time as they’re ready to use it. While it’s true that there are edge cases where additive changes could cause unintended breakages, in general this is a good rule to follow.

  • Keep optional things optional API modifications that transform once optional things into hard requirements break previously established contracts and expectations. API providers should minimize future occurrences in which optional elements become required in order to maintain status-quo system functionality.  

  • Preserve processing rules We can think of this a catch-all bucket for any modifications that alter the business or system logic used to process invocations of the API. This can include caching strategies, rate-limiting rules, or response times. While these types of changes don’t necessarily modify the interface, they could cause unintended consequences in a downstream system that isn’t expecting such changes.

Despite best intentions, sometimes breaking changes to the API are unavoidable. It could be that a new feature changes the function and structure of fundamental business objects or calls. Data formats and/or  protocols may require deep-seeded changes in order to realize performance increases or security enhancements. Reasons aside, API providers can do several things in order to mitigate the pain associated with breaking changes:

  • Provide a clear versioning scheme   Whether it’s semantic versioning, timestamps, or continuous versioning, API providers should clearly communicate the format of the chosen versioning scheme and the corresponding semantics which will enable API consumers to proactively build a successful strategy into their integrations.

  • Summarize and guide Provide a summary of the specific parts of the interface that have been modified and guidance as to what parts of the interface need to be updated. This reduces uncertainty for the API consumer and gives critical information that can aid in assessing the overall level of effort needed to apply the upgrade.

  • Communicate a policy for version deprecation and decommission While not every API consumer may be able to upgrade to the latest and greatest version of an API, they should have a clear understanding of how long they can expect a given version to function so they can plan accordingly.

At Recurly, we communicate a policy to our customers and partners stating that deprecation of specific versions of our API will occur two years after release, with subsequent decommission six months after deprecation. This sets expectations up-front, empowering our customers and partners to make the right decision for their businesses without being blindsided.