Evolving REST APIs
On This Lesson 4 topics
This lesson is planned. The outline below lists the topics it will cover. The full lesson has not been published yet.
In this lesson
change a REST API without breaking clients.
Planned topics
- Prefer additive change: add the new field next to the old one.
- Expand and contract: add new, migrate consumers, remove old in a later release.
- A new version (
/v2, media type, header) is for changes that cannot be made additively; do not version every change. - Keep error shapes stable (for example RFC 9457 problem details).
- Verify compatibility automatically: contract tests (MID-045) and OpenAPI diff tools in CI.
Draft outline details
Demonstration
total stays; add money: {amount: "12.50", currency: "EUR"}. Both are returned for one release.
Check your understanding
What are the three phases of expand and contract?
Show answer
Expand: add new; migrate consumers; contract: remove old.
Practice
Apply this lesson with the module's lab, exercises and quiz.
Marking a lesson complete is optional and you can undo it any time. Your progress stays in this browser.