Versioning strategies
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
compare ways to evolve an API without breaking clients.
Planned topics
- A breaking change (removing or renaming a field, changing meaning) breaks existing clients.
- URL versioning:
/v1/products. Visible and simple; the most common. - Header versioning: a custom header such as
X-API-Version: 2. Clean URLs, but harder to test in a browser. - Media-type versioning:
Accept: application/vnd.shop.v2+json. Precise, but more complex. - Adding optional fields is not breaking. Choose one strategy and use it everywhere.
Draft outline details
Demonstration
| Strategy | Example | Trade-off |
|---|---|---|
| URL | /v2/products | Simple, visible |
| Header | X-API-Version: 2 | Clean URLs |
| Media type | Accept: ...v2+json | Precise, complex |
Check your understanding
Is adding an optional response field a breaking change?
Show answer
No.
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.