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:
- If you’re adding only, go ahead and just add it to the representation. Your clients should ignore what they don’t understand.
- 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).
- 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.