Evolution Techniques for RESTful APIs

This is a follow-up to UIs for Machines: Design Principles for HTTP APIs. One of the principles outlined in the original article is Evolution, and it suggests that developers should strive to keep their API relevant and up to date without sacrificing usability and backwards compatibility.

If You Can’t Measure It, You Can’t Change It

Understanding user behavior is the first step towards avoiding disruptive changes: once you have a sense of how users interact with your API, you can take extra care when working on those parts they use most often. An example is having a different deprecation policy for critical endpoints, or even avoiding deprecation altogether in favor of creating a new API version.

Go the Extra Mile with Versioning

Versioning is a technique widely recommended and adopted in APIs, and for very good (and obvious) reasons. Unfortunately, respecting a versioning policy can be especially hard without the proper infrastructure in place — which is why a lot of APIs have a hard time not breaking their contracts. Endpoint behavior updating without notice, resources changing in format, arguments becoming required are all consequences of a badly enforced versioning scheme.


If there’s only one technique you can adopt from this article, then forget about request migrations and metrics and just focus on communicating with your users — do everything in your power to keep them in the loop about what’s going on. Here are some ideas:

  • Write a changelog. You should do this regardless. Keep a changelog on your API and make it public. Require developers to document any public interface changes in the changelog. If it’s the first time you write a changelog, check out my article, The Changelog-Versioning Revolution, and Keep a Changelog.
  • Use HTTP headers. HTTP has a standard Warning header that can be used to note any useful information about the request/response. You can use this to indicate that the client is using a deprecated endpoint/payload structure. If you provide API bindings, you could also ensure that these messages are logged somewhere for your user to inspect.


In this article, I have presented several different options for evolving your APIs. While it may be tempting to just adopt all of them to ensure the best possible experience for your users, keep in mind that their implementation can be costly in terms of development and maintenance effort, so figure out what works best for your use case and what you can afford to do.

Technology leader and strategic advisor. I work at the intersection of people, software and words.