Mission 1 API Design Review and Improvement Lab Guide
📥 Lab input
- •
day4_api_review_dialogue.md(meeting transcript)
💾 Lab output
- •
design-decision-log.md(API review and improvement doc)
1. Story and lab background
An outside architecture advisor looks at a startup's first API docs and points out: "Your URL structure uses verbs like `/api/v1/getUsers`, and on errors you return HTTP Status 200 OK with the error message inside the Response Body. You also mix PUT and PATCH for updating resources. This structure doesn't follow scalable, standard developer tool conventions and will cost a lot of refactoring later."
If you don't follow standard API design ideas and style rules (REST API standards, naming rules, consistent error formats) early in design, it creates development barriers for external integrations (payment PG, partners).
In this mission, you'll learn to use Codex to write the reasons behind data normalization and architecture decisions from the technical design stage as a structured Design Decision Log, and safely manage the system's history and design reasons (Why).
2. Learning goals
- Accurately extract normalization and database structure decisions from meeting notes.
- Write down the decision item, background reason, alternatives reviewed, approver and chance of future change.
- Record the history of design decisions (Why) to prevent repeat meetings and mistakes by new team members.
🛠️ Follow-along lab guide
- Create lab files: press the download buttons below and save the API spec draft and review meeting transcript in the
automation/folder. - Hand logging to Codex: send the **Codex request prompt** below in the Codex Client prompt box and build.
- Check the log: review whether the decision ID (DEC-003), background, alternatives reviewed (rejection reasons) and approver are structured correctly.
Download lab materials (2 files)
Codex request prompt
Mission 01 Prompt
Review the API spec in the provided day4_api_specification_v1.md, analyze improvements based on REST API design standards (HTTP Method use, URL naming), a consistent error handling structure and scalability, and write an API review report.
4. Example output
Codex documents the architectural conclusions and the trade-off reasons from the conversation like this.
• Decision: instead of storing cancellation history directly in the Reservations table, design a separate Reservation_Histories table with a 1:N split.
• AS-IS (current design): booking status changes often, so this avoids Write Lock bottlenecks on the main table and meets the need to trace history by date and counselor.
• Alternative reviewed: add canceled_at and cancel_reason directly to the Reservations table (rejected: can't record multiple cancellations, and the table would grow too big)
• Approved by: PM and Lead Engineer (approver: Dev_Lead)
• Future change: history may move to a NoSQL Document DB if traffic gets very large.