How to refactor an API

Question

How do you deal with APIs that should be refactored, while not breaking the clients that use the API?

One possible solution I came across: recording refactors to the API, providing the recording to clients of the API which can then apply the refactors to their code: https://netfiles.uiuc.edu/dig/papers/Thesis.pdf

Does such a thing exist for Python? Are there other solutions?

Answer 1

You could always provide a bridging layer which looks exactly like the old api, but calls on new functionality where you've made breaking changes. That way old clients can talk to your compatibility api, while new clients may use your new and improved layer.

Answer 2

It's rather simple, at least in theory — don't ever remove anything, deprecate old stuff instead, while adding new, improved stuff. Don't remove functionality exposed by the deprecated APIs, or emulate it.

Whether your deprecation period (after which you actually remove deprecated stuff) should be short, long or infinite, depends on what the API is, and how many people are using it. If you're using meaningful version numbers, then the rule of thumb is to never break API, unless a major version number changes.