Module 4: API Design & Contract Evolution: Mistake Clinic

This clinic turns wrong moves into reusable judgment. Use it after each practice page and again before the quiz or checkpoint.

---

Module-Specific Mistake Radar

Start with these traps. Replace or extend them with real mistakes from your own work.

Mistake to look for	Where it shows up	Symptom	Repair evidence
Finishing REST API Design Workshop with only a final answer	REST API Design Workshop	The work has no failed case, trace, test, proof gap, or design stress point.	Add the smallest broken example and show the repair that changes the result.
Finishing Integration Style Clinic with only a final answer	Integration Style Clinic	The work has no failed case, trace, test, proof gap, or design stress point.	Add the smallest broken example and show the repair that changes the result.
Finishing Evolution and Compatibility Lab with only a final answer	Evolution and Compatibility Lab	The work has no failed case, trace, test, proof gap, or design stress point.	Add the smallest broken example and show the repair that changes the result.
Finishing Code Katas with only a final answer	Code Katas	The work has no failed case, trace, test, proof gap, or design stress point.	Add the smallest broken example and show the repair that changes the result.
Treating What an API Contract Is and Who It Is For as vocabulary instead of a tool	What an API Contract Is and Who It Is For	The explanation names the concept but cannot decide between two cases.	Write one example, one non-example, and the rule that separates them.
Treating The Developer Experience Lens: Errors, Docs, Consistency as vocabulary instead of a tool	The Developer Experience Lens: Errors, Docs, Consistency	The explanation names the concept but cannot decide between two cases.	Write one example, one non-example, and the rule that separates them.

---

Practice Mistake Checks

Pull any miss from these checks into your mistake log.

REST API Design Workshop

Source: practice/01-rest-api-design-workshop.md

Identify the error in each:

1. POST /getUser/{id} retrieves a user by ID.
2. DELETE /orders/{id} cancels an order by setting status: cancelled.
3. GET /tickets returns all tickets in the system with no pagination - "we only have 8000, it'll be fine."
4. Validation errors return 500 Internal Server Error with a message field.
5. The API uses snake_case on some endpoints and camelCase on others because "the legacy endpoints predate the style guide."
6. Pagination uses ?page=3&per_page=50 and the response has no tiebreaker in the sort.
7. Errors on different endpoints have different shapes: { error: "..." }, { message: "..." }, { errors: [...] }.
8. POST /payments has no idempotency mechanism and clients retry on timeout.

Integration Style Clinic

Source: practice/02-integration-style-clinic.md

Identify the error or risk in each:

1. "We're using GraphQL so clients can request only the fields they need - we don't need rate limits."
2. "Our internal service has 4 methods; we're using gRPC so we get types."
3. "Webhooks are fire-and-forget; if the consumer is down that's their problem."
4. "Event schemas don't need versioning because consumers just ignore unknown fields."
5. "REST is always the right default for a public API." (Is it? When not?)
6. "gRPC over the public internet is fine - we'll just add grpc-web at the edge."

Evolution and Compatibility Lab

Source: practice/03-evolution-compatibility-lab.md

Identify the error in each:

1. "Adding a field is always safe." (What configuration of client parser makes this false?)
2. "We're changing amount from dollars to cents in v1.2 because it's just a unit change."
3. "The endpoint is now deprecated. We removed it from the docs. That should be enough."
4. "Our sunset was last week; we kept it running anyway because a customer asked."
5. "We're moving the currency inside a nested money object. Old clients will just ignore the extra nesting."

---

Repair Protocol

For each real mistake:

1. Reproduce the failure on the smallest example, trace, proof, query, command, or design sketch.
2. Name the hidden assumption.
3. Repair the artifact.
4. Save evidence that changed: failing then passing test, corrected proof step, revised diagram, safer command, benchmark, or review note.
5. Add one retrieval card beginning with Check... before... or Do not use... when....

---

Mistake Log

Date	Mistake	Symptom	Root cause	Repair evidence	Retrieval card
Starter	Pick one radar row above	Explain how it would fail in this module	Name the assumption	Add a counterexample or corrected artifact	Write the card before closing the page

---

Completion Standard

• At least five real mistakes are logged.
• At least two mistakes include a counterexample or failing test.
• At least one mistake connects to an older semester skill.
• At least one correction changes code, a proof, a diagram, a command transcript, a query, or a design decision.