Phase 7: Capstone · ~40 minutes · Design · REST API planning

Design the Service

Endpoints, storage, and failure modes decided on paper are cheap to change. The same decisions discovered mid-implementation are not.

Hiring signal: Designs a service's endpoints, data model, and failure modes in writing before opening an editor

What you will learn

Design a small REST service's endpoints and data storage before writing implementation code
Identify what could realistically fail for each endpoint and plan for it upfront
Plan a test list alongside the design, per Course 01 and this course's Phase 05 discipline
Apply every prior phase's concepts (environments, APIs, databases, debugging) to one real project

Introduction

Type: Project Languages: REST API design Prerequisites: Phases 00-06 (all of Engineering Practices & Tooling) Time: ~40 minutes

Objective

Learning objectives

Design a small REST service's endpoints and data storage before writing implementation code
Identify what could realistically fail for each endpoint and plan for it upfront
Plan a test list alongside the design, per Course 01 and this course's Phase 05 discipline
Apply every prior phase's concepts (environments, APIs, databases, debugging) to one real project

What you're building

A written design (design.md) for your chosen service:

Endpoints: every planned endpoint, its HTTP verb, what it does, and — critically — at least one realistic failure mode per endpoint and how it should be handled (a specific status code, not just "an error")
Storage: your data model (table(s) and columns, or your justified choice per Phase 04's schema-design lesson if a document model genuinely fits better)
Config: what will vary by environment (at minimum: where the database lives) and how it'll be read — no hardcoded values planned
Test plan: at least 6 named tests, each testing one specific behavior, including at least one deliberate edge case (an ID that doesn't exist, a malformed request, or similar)
One paragraph on what you expect to be the trickiest part of building this, and why

A design lists an endpoint DELETE /bookmarks/{id} with no stated failure mode — the design assumes the ID always exists. What's the risk of shipping this design as written?

This is exactly the discipline this lesson is built around: GET /bookmarks/{id}'s design explicitly planned for a nonexistent ID (404); DELETE /bookmarks/{id} has the identical shape of risk (an ID that isn't there) and wasn't planned for at all. Idempotency (Phase 03) describes what happens if the SAME valid request is repeated — it says nothing about what happens when the target doesn't exist in the first place. Leaving this unplanned doesn't make the case impossible; it just means it'll be discovered and decided under implementation pressure instead of calmly, on paper, right now.

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers The Problem, Check Yourself, Key Terms & Next — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.