The Tricks of API Versioning

An API is a contract to perform a specific service when a specific request comes in. Changing how the API behaves can cause unanticipated ripple effects for API users since they spent time configuring their software around its behavior at the time of implementation. Much like remodeling a kitchen around an existing plumbing system—changing the structure of the kitchen each time the plumbing needs fixing can be a cumbersome and disruptive task. This can stifle the development of your API since new capabilities need to be created, but you don’t want to break things for your current customers or have them gut their kitchen because you changed the plumbing. Enter API versioning: the solution to allowing API users to not have their software break when you update your API.

At Shippo, we considered several approaches to versioning our API. Our questions throughout this  process were:

• Does it enable us to make backward incompatible API changes that fit with the short-term and long-term product roadmap?
• How many engineering resources do we need to invest to build this?
• Is each version testable, and how sure can we be that changes in one version do not unintentionally affect the other versions?

Here are the three approaches we considered as a team before moving forward.

1) A proxy that points requests to different versioned codebases

A proxy approach is the most flexible in terms of what can be accomplished since you can change everything about your API between versions. You could implement a whole new architecture or a new design. This sounds amazing, but it does come with some significant logistical drawbacks. For starters, you have to maintain a static version of the API pointing to your old codebase. This means keeping around a lot of legacy code and services. Additionally, data migrations could end up being very painful and challenging. Finally, you would likely end up with a lot of code duplication, which just a waste of engineering’s resources to have to reinvent the wheel between API versions.

2) A router with versioned controllers

Having a router with versioned controllers means that you would have a shared model and only change the behavior for controllers of each version of the API. This allows you to avoid duplication of code and save time as a result of that. This too sounds very enticing, but does come with a drawback of the possibility of breaking previous versions of the API. You end up needing robust and reliable tests to ensure nothing breaks with successive versions.

3) A router that shares controllers but has versioned views

This is a very similar approach to the previous one, but rather than version the controller we version the views. You end up sharing a lot more resources, so it requires the least amount of work for making newer versions of the API. You don’t need to data migrations since the model is shared and it has the least code duplication. It does, however, still have the drawback of possibly breaking previous versions of the API.

Our Final Decision

We ultimately decided to go with the third approach—using a router that shares controllers but has versioned views. We needed something that would be fast to implement, and there wasn’t a need to rewrite our data models with this approach. It aligned with all of the backwards incompatible changes that we needed to make. For each new version of our API, we simply create a new versioned view and deliver the changes on to our users. Our most recent update to our API cleaned up a lot of fields and deprecated unnecessary ones. The process was seamless since users can upgrade at their own pace.

We know there is no perfect way of handling API versioning, and a lot of compromises must be made to make it work, but we have found what works best for us. At Shippo, we’re seriously concerned with ensuring our users have a solid and consistent experience when interacting with our API. As newer and better features start to come out that entice a user to upgrade, they can always start implementing by just specifying in their headers to use the most recent version of the API. Once they’re built out, they can just upgrade in their dashboard.

Feature image via Pixabay.