BT
x Your opinion matters! Please fill in the InfoQ Survey about your reading habits!

Experiences Versioning a RESTful Service

by Jan Stenberg on Sep 16, 2013 |

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.

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

Discuss

Educational Content

General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2014 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT