in REST

Avoid Versioning – Please

Peter Williams recently made a good proposal suggesting content-negotiation as a means to advertise and ask for version support. This is in contrast to using version identifiers in URIs as is commonly done. This is a neat idea. Peter’s post prompted some debate and a rebuttal. But I find that this debate is a distraction.

In my view, the real problems that every interface designer must be concerned about every day are (a) maintaining compatibility with the interface’s clients, and (b) avoiding versioning.

Yes, avoiding versioning!

Versioning is a hack and is a clever disguise to hide the fact the interface has broken its contract with its clients, and needs clients to start all over again (i.e. upgrade to a newer version of the contract).

So, please please avoid versioning. I don’t care how pretty one versioning solution is over another versioning solution, if it requires clients to change their code. If it does not require clients to change their code, the changes to the interface are, after all, compatible, and hence do not require a change in the version.

Write a Comment

Comment

  1. I agree that in a perfect world we would not need versioning. But we don’t live in that world. I have *never* written a program in which I fully understood the problem until well after I had released the first version. As humans we are doomed to producing useful things based on incomplete understanding and information.

    Versioning is a fact of API development and mantenaince. It may be unpleasant but it does not get easier or less likely just because you ignore it.

    Oh and a good versioning mechanism should allow you to continue to support your existing contracts and support new ones at the same time. It should not break any existing contracts.

  2. I don’t disagree. That’s why the compat problem is extremely challenging and it takes some iterations early on to get the contract amenable to compatible changes. I think we should treat versioning as an emergency eject button – i.e. to be used only when all other attempts failed.

  3. I understand the need to limit ‘drift’ in code and data. I think it can be a sign of shoddy work if the application is constantly changing without clear direction, etc. But I also have another view, based on my current projects.

    I work in an environment where not all of our B2B customers are subscribed to the same version of our Web-based apps. For us, versioning (of both data and workflow) is not an ‘emergency eject button.’ It’s a fundamental part of our work.

  4. Mike – in your experience, did you have to consider versioning since compat could not be maintained? Or is it for some other business reasons? If it is the latter, I completely agree. My intent is to address the former situation.

  5. Good point. In most cases, versioning is a way to partition features for our clients. Often this is a business-driven item (‘hey, you should upgrade to the new mauve edition of super-app #123!’). In some cases, our clients have competing interests and features need to be segmented in a way that prevents incompatibilities, but these are in the minority.