REST API Versioning Strategy for a 4-Year-Old Public API
Overview
What this challenge is about.
Pick a versioning scheme (URI path vs header-based) and justify it against integrator behavior. Define the deprecation lifecycle: announce → deprecate → sunset, with concrete timelines (e.g., 12-month minimum overlap). Build a breaking-change checklist and a CI hook that blocks PRs introducing breaking changes without explicit annotation. Wire up an OpenAPI-driven SDK code-generation pipeline (TypeScript, Python, Go). Draft a 4-message customer communication sequence with copy. Deliver: policy doc (8 pages), CI hook, SDK pipeline, communication sequence, and a sunsetting plan for the 6 oldest endpoints.
The Brief
What you'll do, and what you'll demonstrate.
Design a REST API versioning strategy and deprecation lifecycle that supports two concurrent major versions and prevents another breaking-change incident.
Earning criteria — what you'll demonstrate
- Compare URI vs header-based versioning schemes by integrator impact
- Design a deprecation lifecycle with enforceable timelines
- Use OpenAPI as the single source of truth for SDKs and breaking-change checks
- Coordinate engineering, support, and customer communication around deprecation
Program Fit
Where this fits in your program.
Sharpens the same skills your degree expects you to demonstrate.
Skills
Skills you'll demonstrate.
Each one shows up on your verified credential.
Careers
Roles this prepares you for.
Real titles. Real skill bridges. Pick the one closest to your trajectory.
Product Manager
PMs on developer-platform products who can co-own the deprecation lifecycle are the rare partners engineers actually trust with API roadmap.
This challenge sharpens
- api-versioning
- deprecation-lifecycle
- developer-experience