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.

Compatibility evidence core

Use the executable compatibility package for Lab 3. Preserve the actual HTTP, durable retry, restart, concurrent request, expiry, rollback and independent consumer-review evidence; the finite checker does not replace these.