I was recently asked what my opinion was on REST versioning, a few years after having written http://www.informit.com/articles/article.aspx?p=1566460 and after having recorded some stuff for Pluralsight on versioning as well. The questions were general purpose enough that I thought I’d share my answer on the blog. Here are the questions and my answers:

1. Given 2.5 years since the article, have you seen any shift toward one or the other method in the industry?

What I’ve seen in behavior is that people only change the URL for breaking changes. They try like crazy to always use the same endpoint for everything, including new functionality. I have seen a lot of uptake with the WebAPI bits released in .NET 4.5. Some companies have gone NUTS on the ability to negotiate content types, and this is for applications for big companies with thousands to millions of customers.

For APIs meant to be consumed by less process oriented folks, I see more APIs that just use JSON. The API owner then documents things for internal SDK development teams. What appears to happen is the internal SDK development teams ‘test’ the docs by building APIs in .NET, Ruby, PHP, Java, Objective C, and so on. When this phase is done, the QA’d REST documents and resulting SDK documentation is published. Development of an SDK seems to be done in an effort to make API adoption easier and to reduce the amount of support needed to get API consumers up and running.

If I was leading a REST API development project, I would design a good structure, document whatever the team did for the REST API, and then lean on the SDK as the only well supported mechanism for accessing the API. This move would let the team build a nice SDK without worrying about making sure everyone can understand the REST documentation. The reality is that most developers do not know and do not want to fully understand the intricacies of content negotiation, cache headers, and so on. They just want to build software. Your job is to worry about these things and a good SDK makes it easier for all users to do the right things.  

2. If you were building a new API today what direction would you go?

I’m reading this as a SOAP question as well as a “how do I build a REST endpoint today?” question. The answer is: it depends. If I need the API to be consumed by internal endpoints, SOAP gives me a faster way to build things and, since the app is internal, it’s highly likely that transaction consistency, security, and an RPC-like calling convention fit in well with the existing needs. I’d still version endpoints as much as I could, but reality is that most places roll out new versions of systems that need to be versioned in lockstep due to business and regulatory concerns that versioning simply does not care about. Oftentimes, the reason for the new version is new requirements that make the old version obsolete.

For external APIs, I’d only ever use HTTP based APIs. Then, the question is obviously: do you create new media types and use content negotiation, do you use new endpoints for version changes, or do you use something else? My preference today is to use new endpoints and worry about wiring things up correctly under the covers. Doing this allows me to monitor usage of each version using existing HTTP log scraping tools and seeing which URLs are being used most heavily. For everything else: how RESTful I am vs. just using HTTP as an RPC mechanism, data types, payloads, and so on, I’d stick with building SDKs as the preferred method to interact with the service. I value good design but I hate arguing about things like whether or not the ETags are configured correctly. The SDK documents the API team’s decisions where those arguments happened and let’s everyone else just use things.

3. Do you know of any particularly good resources on the topic of the top of your head that don’t come up in google and bing?

Actually, no. It seems like a lot of great stuff was written about designing REST APIs and what I’ve found on the various search engines all seems pretty decent. Today, tools like WebAPI from Microsoft and others make it easy to do the right things as an API developer.