API: schema versioning
This course covers versioning a JSON API in Rails. It starts with why a response shape is a promise to external clients, such as partner integrations. It then compares versioning in the URL path with namespaced routes against versioning in an Accept header with a registered MIME type and a routing constraint. It sets out which changes break clients and which are safe. It shows how to share Jbuilder partials and Ruby modules across versions, and how to deprecate a version with Deprecation and Sunset headers.
What you'll learn
- ✓Why a correct change to a JSON response can still break external clients
- ✓URL-path versioning with nested Rails namespaces and version-specific controllers
- ✓Header-based versioning with Mime::Type.register and a routing constraint object
- ✓Which changes are additive and safe, and which removals, renames or narrowed inputs break clients
- ✓Sharing partials and Ruby modules across versions, and deprecating a version with Deprecation and Sunset headers
Why an API needs a version at all
An internal HTML page can change shape overnight. Every visitor gets the new markup on the next request, because nothing outside your own deploy reads that HTML as data. A JSON API response is different as soon as one outside client parses it. Change the shape, and every client still expecting the…
Read the full lesson free →Curriculum
7 lessonsWhy an API needs a version at all
Shows how a correct change, like moving totals to integer cents, breaks external API clients your tests never see.
URL-path versioning: the shape most Rails apps reach for first
Puts the version in the path with nested namespaces, giving separate controllers per version and visible, cache-friendly URLs.
Header-based versioning, and its real Rails plumbing
Routes one stable URL to different versions using a registered vendor MIME type and a constraint reading the Accept header.
What actually counts as a breaking change
Separates safe added keys from breaking removals, renames, changed value meanings and stricter validation of accepted input.
Versioning the response shape without duplicating the app
Shares fields through json.partial! and computation through Ruby modules, while keeping each version's response shape in its own view.
Deprecating a version without breaking it out from under people
Marks an old version with Deprecation and Sunset headers, keeping it working until a person decides to turn it off.
Putting it together: two shapes, one honest transition
Reviews the six lessons and presents a Ruby challenge that renders one canonical piece of data per requested version.