Versioning and Backward Compatibility
Learn to make additive changes safely, choose a versioning strategy, and retire old endpoints gracefully using the current IETF-standardized Deprecation and Sunset response headers instead of just breaking clients without warning.
Prerequisites: completion of REST API Design Principles (or an existing REST API to work against); comfort writing middleware in your framework of choice.
Version note: verified against RFC 9745 (The Deprecation HTTP Response Header Field, March 2025), RFC 8594 (The Sunset HTTP Header Field, May 2019), and RFC 8288 (Web Linking, October 2017). All three are published, stable IETF standards — this is one part of API design where the tooling has fully caught up to a real spec rather than relying on draft conventions.
Most API changes don't need a new version at all. A change is non-breaking if every existing client keeps working without modification: adding a new optional field to a response, adding a new endpoint, adding a new optional query parameter, or making a required request field optional are all safe. A change is breaking the moment it can make an existing, unmodified client fail: removing or renaming a field, changing a field's type or meaning, adding a new required request field, or changing a status code an existing client branches on.
This project takes the task API from the previous project and walks through both paths: extending it safely, and then making a genuine breaking change the right way.
Test what you just learned
Self-testing is one of the best ways to retain new skills. Unlock project quizzes to check your understanding.
Log in to unlock0 / 7 complete