Chapter 21: Versioning

Versioning a REST API is an inevitable process that puts a significant burden on the development team. Before you ask yourself “How should we version the API?”, I recommend spending time on the question “What can we do to avoid versioning in the first place?”. You’ll probably come up with several strategies to postpone the need for versioning as much as possible.

Once a REST API is made publicly available to developers, integrations begin to appear and these integrations later prevent major changes to the current API structure. Every change must remain backward-compatible to avoid breaking existing integrations. That’s why avoiding versioning whenever possible is such an important goal. It’s not easy, but here’s one piece of advice:

During the design process, keep asking yourself what new scenarios might arise in the future, and whether you’ll be able to support them while staying backward-compatible. You won’t be able to anticipate every edge case, but you should always be able to cover the core scenarios without the client noticing any difference. If not, adjust the design until that’s possible.