Module 4: API Design & Contract Evolution: Guided Labs

Lab 1: Contract-First Resource API

Design a small API from consumer tasks. Specify resources, methods, status codes, error format, validation, authentication boundary, filtering, stable ordering, cursor pagination, and rate-limit behavior before implementation.

Lab 2: Retry and Idempotency Harness

Inject a lost response after a successful mutation. Demonstrate the duplicate effect, then add durable idempotency handling, request fingerprinting, concurrent-retry behavior, and expiry policy.

Lab 3: Compatibility Migration

Evolve one request and one response across old and new consumers. Add contract tests, compatibility fixtures, deprecation headers/documentation, usage telemetry, and a rollback. Prove both versions work during the window.

Lab 4: Adversarial Consumer Review

Have another learner build against documentation only. Capture ambiguities, invalid assumptions, and missing failure semantics; repair the contract rather than coaching around it.

Evidence: API specification, tests, migration timeline, telemetry plan, and consumer review log.