프롬프트 두 번으로 만든 API 서버, 그리고 "에러까지 가르치는" 학습 화면

소개

Claude Code에게 FastAPI 서버 하나(엔드포인트 4개)와, 그 서버에 요청을 보내고 응답이 돌아오는 과정을 애니메이션으로 보여주는 학습용 웹 화면을 만들었습니다.

왜 했나: 과제 스펙은 "서버 하나, 엔드포인트 세 개"였는데, curl로 JSON만 주고받으면 API가 뭘 하는 건지 감이 잘 안 왔습니다. 요청이 날아가고 응답이 돌아오는 걸 눈으로 보면서 배우고 싶었습니다.

그런데 만들고 보니 이 화면의 핵심은 성공(200) 화면이 아니었습니다. 일부러 404와 422 에러를 만들어보는 버튼이 가장 좋은 학습 장치가 됐다는 게 이번 사례의 축입니다.

진행 방법

사용 도구

• Claude Code (Fable 5 모델) — 설계·코드 작성·테스트·스크린샷 캡처 전부

• Python 3.14.5 + FastAPI 0.139.2 + uvicorn — API 서버

• HTML/CSS/JS (바닐라, 프레임워크 없음) — 학습 화면 1개 파일

• Playwright — 학습 화면 스크린샷 자동 캡처

1단계. 자연어 요구사항 → 서버 (프롬프트 1개)

API 서버를 만들려고 해.
오늘 만들 것 - 서버 하나, 엔드포인트 세 개
•① GET/hello - 인사말 JSON. 몸풀기입니다.
② GET /나만의-무언가 - 내 소재로 엔드포인트 하나. 내 취미 메뉴판, 오늘 할 일, 아무거나.
POST /나만의-무언가 - 데이터를 받아서, 그걸 섞어 돌려주기.
이것을 바탕으로 API를 만들자.
스터디 참여자에 대한 정보를 제공하고 스터디 참여자인 클라이언트 상대방이 인사를 하면 인사를 하는 것, 스터디 참여자를 get으로 요청하면 스터디 참여자 리스트를 돌려주고, 스터디 참여자의 이름과 알고 싶은 스터디 참여자의 특정요소 하나 (관심사, 기대내용, 과제 수행 횟수, 수료 여부)등을 post로 요청하면 그에 대한 답을 주도록 만들어보자.

Tip: REST 규칙 같은 기술 용어 없이 "누가 인사하면 인사하고, 이름과 항목을 보내면 답한다"처럼 역할 중심으로 썼는데, AI가 이걸 알아서 엔드포인트 4개로 설계했습니다. 알고 싶은 항목 4가지(관심사, 기대내용, 과제 수행 횟수, 수료 여부)를 괄호 안에 명시한 덕에 요청 스키마가 한 번에 확정됐습니다.

→ 결과: 가상환경 생성, FastAPI 설치, main.py 작성, 서버 실행, curl 테스트 5건까지 한 턴에 완료됐습니다.

여기서 첫 번째 예상 밖: 스펙은 3개였는데 4개가 됐습니다. "인사를 받으면 인사로 답한다"는 데이터를 받아야 하니 GET으로는 안 되고, POST /hello가 따로 필요했습니다. 같은 경로(/hello)에 GET과 POST가 공존할 수 있다는 것 자체가 첫 학습 포인트였습니다.

실제 테스트 출력 일부:

--- POST /participants (수료 여부)
{"name":"이서연","field":"수료 여부","value":true,"answer":"이서연님은 수료하셨습니다."}
--- POST /participants (없는 사람)
{"detail":"'홍길동'님은 참여자 명단에 없습니다. 현재 참여자: 예슘, 김민준, 이서연, 박지훈"}

ALT

검정색 배경의 웹페이지 스크린샷

2단계. 요청/응답을 눈으로 배우는 화면 (프롬프트 1개)

더미 데이터를 임시로 만들고 이를 시각적으로 프로그램으로 만들어서 요청과 응답에대한 방식들을 시각적으로 학습할 수 있는 화면이 있는 프로그램으로 완성하자

Tip: "시각적으로 학습할 수 있는 화면"이라는 목적만 말하고 구현 방식(어떤 라이브러리, 어떤 레이아웃)은 전부 비워뒀습니다. 그 결과 미니 포스트맨 + 패킷 애니메이션 + 상태 코드 해설이라는, 제가 구체적으로 떠올리지 못했던 구성이 나왔습니다.

→ 결과: 더미 데이터가 6명으로 늘고, index.html(389줄) 한 파일짜리 화면이 서버 루트(/)에 붙었습니다. 화면 구성은 4개 패널입니다.

1. 엔드포인트 목록 — GET(초록)/POST(주황) 배지, 선택할 때마다 "GET은 '주세요' 요청, POST는 봉투에 담아 보내는 요청" 같은 개념 설명이 바뀜

2. 요청 만들기 — POST 선택 시 JSON 본문 편집기 + 프리셋 버튼 8개

3. 흐름 애니메이션 — 💻 클라이언트 → 🖥️ 서버로 요청 패킷이 날아가고, 응답 패킷(초록 200 / 빨강 에러)이 돌아오는 왕복 과정

4. 응답 패널 + 히스토리 — 상태 코드, 소요 시간(ms), 문법 강조된 JSON, 상태 코드 한글 해설

ALT

검정색 배경의 웹페이지 스크린샷

ALT

어두운 방에 있는 코드 편집기의 스크린샷

프리셋 중에 "404 만들기 (홍길동)", "422 만들기 (틀린 항목)" 버튼이 있습니다. 명단에 없는 이름, 규칙에 없는 항목("혈액형")을 일부러 보내서 에러 응답을 관찰하는 용도입니다. 에러를 숨기는 게 아니라 버튼 한 번으로 재현하게 만든 것 — 이게 이 화면에서 제일 마음에 드는 부분입니다.

검증

curl로 화면 제공·참여자 6명 조회·422 반환을 확인했고, Playwright로 실제 브라우저를 띄워 5개 장면(첫 화면, 200 성공 2종, 422, 404+히스토리)을 자동 캡처해 눈으로 검수했습니다.

결과와 배운 점

결과 (숫자로)

ALT

다양한 옵션이 표시된 검은색 화면의 스크린샷

🔑 꿀팁 3가지

1. 학습용 도구를 만들 땐 "실패 재현 버튼"을 넣어달라고 하세요

성공 경로만 보여주는 데모는 금방 시시해집니다. 404·422를 버튼 한 번으로 일부러 만들 수 있게 하니, 에러 메시지를 읽는 것 자체가 놀이가 됐습니다. API가 아니어도 — 엑셀 자동화든 챗봇이든 — "일부러 틀려보는 입력"을 준비해두면 학습 효과가 다릅니다.

2. 요구사항은 기술 용어가 아니라 역할로 쓰면 됩니다

"REST API를 설계해줘"가 아니라 "인사하면 인사하고, 이름과 항목을 보내면 답해줘"라고 썼는데 설계가 한 번에 나왔습니다. 무엇을 주고받는지만 구체적으로 쓰면, HTTP 메서드 선택 같은 기술 결정은 AI가 알아서 합니다.

3. 검증 기능은 직접 짜기 전에 프레임워크에 이미 있는지 확인하세요

아래 시행착오에 적었지만, 422 검증 로직은 한 줄도 안 짰는데 생겼습니다. "이 기능 구현해줘" 전에 "이거 프레임워크가 해주지 않아?"라고 물으면 코드가 줄어듭니다.

😅 시행착오

솔직히 이번엔 에러도 실패한 시도도 없었습니다. 대신 예상과 달랐던 것 세 가지를 적습니다.

① 엔드포인트가 3개 스펙인데 4개가 나왔습니다

"인사를 받으면 인사로 답한다"는 요구는 데이터를 받아야 해서 GET으로 구현이 안 됩니다. AI가 POST /hello를 추가하면서 같은 경로에 GET/POST 두 메서드가 공존하게 됐는데, 스펙과 다르다고 지적하는 대신 왜 그렇게 됐는지 이해하는 쪽이 남는 게 많았습니다.

② 422 에러를 구현한 적이 없는데 동작했습니다

요청 모델에 허용 항목을 타입으로 선언만 해뒀는데:

class ParticipantQuery(BaseModel):
    name: str
    field: Literal["관심사", "기대내용", "과제 수행 횟수", "수료 여부"]

"혈액형"을 보내면 FastAPI(Pydantic)가 자동으로 이런 422 응답을 만들어 줬습니다:

{
  "type": "literal_error",
  "loc": ["body", "field"],
  "msg": "Input should be '관심사', '기대내용', '과제 수행 횟수' or '수료 여부'",
  "input": "혈액형"
}

허용값 목록까지 에러 메시지에 넣어주는 건 기대하지 않았던 부분입니다. 학습 화면의 "422 만들기" 프리셋은 이 공짜 기능 위에 얹은 것뿐입니다.

ALT

검정색 배경의 웹페이지 스크린샷

③ 첫 실행 환경에 FastAPI가 없었습니다

Python 3.14 기본 환경이라 no fastapi 상태였고, AI가 먼저 환경을 확인한 뒤 가상환경(.venv)을 만들어 설치했습니다. 에러는 아니지만, "만들어줘" 전에 환경 확인 단계가 자동으로 들어가는 걸 보고 프롬프트에 환경 얘기를 안 써도 된다는 걸 알았습니다.

한 줄 요약

API 학습의 최고 재료는 성공한 200이 아니라, 버튼 한 번으로 일부러 만들어보는 404와 422였습니다.