The Process for Safely Deploying APIs

Overview

When we get to the point where we plan to release our API updates, we have one more opportunity to check for backward-compatibility issues and confirm that we’ve done all we can to eliminate breakage for our API consumer clients. That means we need to figure out the best way to deploy our updates into production. To cover all these details, we’ll need to focus on a number of things:

• Supporting reversibility
• Using side-by-side deployments
• Automatically routing traffic vs. waiting for clients
• Overwriting old API releases

Supporting reversibility

Ironically, the first thing that we need to do when implementing our API update deployment system is make sure we can quickly and easily take our API out of production. In other words, we need to be able to back out of any API update and revert back to the way things were before we attempted the new deployment. This reversibility is our safety net in case something goes wrong during deployment.

Earlier, we learned the value of scripted deployments. We can consistently run (and rerun) our deployment script knowing that, each time we do, the process is the same. The same is true for reversing our deployment. As soon as we detect a problem with our install, we should be able to instantly undo our latest update.

Don’t Forget Your Data!

Deploying and reversing APIs can be complicated if our change involves adding new data properties to our storage model. If we deploy a new release that starts collecting new data properties and then need to reverse it, we might end up losing the added data we were collecting with the new release. To avoid this, we’ll need to include data capture and recovery as part of our reversibility plans.

The easiest way to do that is to simply rerun the script from our previous deployment. This potentially overwrites our mistakes and sets us back to normal operating conditions. However, there’s another pattern we can use that can be easier to implement and can result in a safer, more stable deployment process: side-by-side deployment.

Using side-by-side deployment

The best approach for releasing updates to existing production APIs is to use a side-by-side release pattern. That means both the new and the existing editions of our API are running production at the same time. Side-by-side deployment allows us to gradually roll out our changes with the least impact on existing services and API consumers.