API & Contract Design
An API is a promise you have to keep.
An API is a contract with consumers you can't see and can't force to upgrade - so designing it well and evolving it without breaking anyone is a senior skill. REST maturity and resource modeling, versioning and backward compatibility, consistent error and idempotency contracts, OpenAPI and consumer-driven contract testing, and treating events as contracts with their own schema evolution.
Lessons in this stage
- 01
REST, Done Properly
IntermediateThe Richardson Maturity Model: resources, HTTP verbs, and status codes used correctly - and where HATEOAS/hypermedia genuinely helps versus where it's overkill.
15 min - 02
Designing Resources
IntermediateModeling resources and URIs (nouns, not verbs), the conventions for pagination, filtering, and sorting, and shaping representations that don't leak your database.
14 min - 03
Versioning & Evolution
AdvancedHow to version (URI vs. header vs. media type), the difference between breaking and non-breaking changes, and the tolerant-reader habit that lets APIs evolve without breaking clients.
16 min - 04
Errors & Idempotency
AdvancedA consistent, machine-readable error contract (RFC 9457 Problem Details) and idempotency keys so a retried request can't double-charge - the contracts that make an API safe to consume.
15 min - 05
Contracts & Consumer-Driven Testing
AdvancedOpenAPI as the machine-readable contract, and consumer-driven contract testing (Pact / Spring Cloud Contract) that catches a breaking change before it reaches production.
15 min - 06
Events Are Contracts Too
AdvancedAsync APIs need the same discipline: an event schema is a contract with every consumer, and evolving it safely means schema compatibility rules and a registry (Avro/JSON Schema).
14 min