5

Suppose I have a library, that basically works as a facade to some cloud service (e.g. JavaScript API that wraps around network calls to some RESTfull service). And once that service introduces a backward-incompatible change.

There are two possible scenarios I can think of, and I'm not really sure how to handle both the best way.

  1. In simpler case, my library somehow manage to handle that backward-incompatibility (and now became an adapter). So I ship an patch version because API of my library did not change, and previous version is now have some kind of a buggy behavior (relies on external API that does not exists any more). The problem here is that all already built programs, as well as ones that uses some kind of dependency locks are now broken and must update their dependencies. Well, I can say that that's not a my problem, but it bugs me a bit.

  2. In more complex and more real case, my library can't abstract that backward-incompatibility and it leaks through it, so I have to change a public API of my library too. So, I ship a major version. The problem is that it breaks the whole point of SemVer, where the user suppose to have the freedom to decide where they want to have a major update or do not, because a previous major version supposed to work along with the new one. But it does not and can't be patched.

I understand that SemVer approach is not supposed to handle such cases. But I have no idea what is supposed to. Is there any approaches to such cases out there?

Dherik
  • 2,406
  • 20
  • 33

1 Answers1

0

The best approach for this is to define your wrapper library in terms of the NEWEST version of the web service API (the presumption being that people will want to migrate towards that, and that it will expose new features but otherwise be similar to the old API).

Have that API wrapper auto-detect the version of the remote service, and provide backward compatibility.

And any APIs which have gone away (or changed materially) - mark as DEPRECATED (the particular overload if needed) - but still support.

That way, when users over your wrapper library encounter new or old servers, they will work either way. And they will get warnings (about the deprecation) if they are using any deprecated APIs, so they can migrate to the newer APIs as makes sense for their projects.

NOTE - this form of backward compatibility is easy todo, and good todo. But its incomplete. If you want old clients to work with newer servers (often a good idea) - you need to employ a SIMILAR approach on the server side, allowing it to detect newer (vs. older) versions of the RESTFULL web service API.

I've used this approach before on several projects, and it has worked very well over the years, allowing customers to use APIs I've built to migrate their own code on their own schedule, as they inter-operate with changing versions of the underlying service/product.

Lewis Pringle
  • 2,935
  • 1
  • 9
  • 15