Experiences Versioning a RESTful Service

| by Jan Stenberg Follow 26 Followers on Sep 16, 2013. Estimated reading time: 1 minute |

A note to our readers: You asked so we have developed a set of features that allow you to reduce the noise: you can get email and web notifications for topics you are interested in. Learn more about our new features.

Use server driven content negotiation, but enhance the response with links to alternate versions and formats of the representation, thus letting the client choose which URIs to follow due to its needs Howard Dierking recently wrote when comparing his newly gained experiences working with designing the next major revision of the NuGet API, v3, with his thoughts almost a year ago.

In his comparison of this real application API with non-trivial scale requirements and a number of different clients, Howard found that he in his original thoughts too much believed in the promise of server-driven content negotiation. Now he finds that this too much puts the client in the hands of the server; the client can ask for a specific representation but it’s still up to the server what the client will receive.
Howards sees an alternative, a hybrid approach, based on server driven content negotiation with a link to the canonical resource, but enhanced with links to alternate variations of a representation. The client can then choose which URIs to follow based on its needs and the metadata provided with the links.

With a presumption that versioning depends on what part of the uniform interface is changed, Howard summarises his new versioning strategies with:

  1. If you’re adding only, go ahead and just add it to the representation. Your clients should ignore what they don’t understand.
  2. If you’re making a breaking change to the representation or changing the meaning of the underlying resource, create a new resource with a new name (URI).
  3. Use content negotiation in such a way that it can provide an optimized path to resources, but always give the client control (by way of links) to make different choices.

Of these three points, only the first one remained unchanged since last year, with the two others revised according to his thoughts today.
Howard Dierking is a developer working on the NuGet API, a package manager for the Microsoft development platform.

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread


Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and don't miss out on content that matters to you