System Design
API Contracts That Survive Version Skips
Design additive changes, deprecation windows, and consumer tests that keep mobile and partner clients aligned.
Overview
Hands-on drafting for OpenAPI and event schemas with a focus on consumer-driven checks and documentation that engineers actually open.
Included
- Contract diff exercises with realistic breaking changes
- Consumer test harness starter kits (language agnostic)
- Deprecation calendar template with owner names
- Workshop on error payload consistency
- Office hours on pagination stability
- Review of one public or internal API per team
- Checklist for documentation drift
Outcomes
- Ship a deprecation notice engineers outside your squad understood on first read.
- Add two consumer tests that caught a regression pre-merge.
- Define a single source of truth for error codes.
Lead contact
Daniel Vance
Curriculum designer; previously documentation guild lead at a multi-region analytics SaaS.
FAQ
GraphQL?
We touch federation patterns briefly; depth is REST-first with optional GraphQL office hour.
Code generation?
Discussed conceptually; we do not mandate a specific codegen toolchain.
What is excluded?
No legal review of partner agreements; focus stays on technical contracts.
Recent notes
“Deprecation calendar is brutally simple and therefore adopted. GraphQL hour was thin but REST modules were dense.”