Day 3 — API 설계: 화면과 서버는 어떻게 대화하나

오늘의 목표

  1. API가 "화면과 서버 사이의 주문서"라는 걸 이해한다
  2. REST 방식으로 엔드포인트(주소)를 설계할 수 있다
  3. 내 프로젝트의 API 명세서 초안을 작성해서 나간다

준비물: Day 2에 만든 ERD 초안

0. 복습 — 지난 시간 우리는

지난 시간에 "무엇을 저장할지"(테이블, 관계)를 설계했습니다. 오늘은 그 저장된 데이터를 "어떻게 꺼내고 넣을지" 의 통로를 만듭니다.

ERD가 창고의 선반 배치도였다면, 오늘 만드는 API는 창고와 손님 사이의 주문 창구입니다.

1. API란? — 식당 비유로 이해하기

API = 화면(손님)이 서버(주방)에 무언가를 요청하는 정해진 방법

식당을 떠올리세요.

  • 손님(프론트엔드): "비빔밥 하나요" 라고 주문
  • 메뉴판(API 명세): 무엇을 주문할 수 있는지 적힌 목록
  • 주방(백엔드/서버): 주문을 받아 음식을 만들어 내보냄
  • 음식(응답 데이터): 손님에게 돌아오는 결과

손님은 주방이 어떻게 요리하는지 몰라도 됩니다. 메뉴판(정해진 약속) 대로 주문하면 음식이 나옵니다. 이 "메뉴판"이 바로 API입니다.

💡 우리 프로젝트에서 프론트는 바이브코딩(AI)으로 만들지만, 이 메뉴판을 여러분이 정확히 설계해야 AI에게 "이 주소로 이런 요청을 보내는 코드를 짜줘"라고 시킬 수 있습니다.

2. HTTP 메서드 — 요청의 4가지 종류

데이터로 할 수 있는 일은 결국 4가지뿐입니다. (Day 2의 CRUD 기억나시죠?)

메서드하는 일CRUD식당 비유
GET조회 (읽기)Read메뉴 구경
POST생성 (만들기)Create새 주문 넣기
PUT / PATCH수정 (바꾸기)Update주문 변경
DELETE삭제 (지우기)Delete주문 취소

💡 PUT은 전체 교체, PATCH는 일부만 수정입니다. 처음엔 PATCH를 주로 쓴다고 생각하면 편합니다.

3. REST — 주소를 짓는 규칙

API 주소(엔드포인트)를 아무렇게나 지으면 나중에 본인도 헷갈립니다. REST는 주소를 일관되게 짓는 약속입니다.

핵심 원칙 3가지

① 주소는 "명사"로, 동사는 메서드로

❌ 나쁜 예:  /getTodos , /createTodo , /deleteTodo
✅ 좋은 예:  GET /todos , POST /todos , DELETE /todos/1

무엇을 할지(가져오기/만들기/지우기)는 메서드가 표현하니, 주소엔 대상(todos)만 씁니다.

② 복수형 명사 사용

✅ /todos  /users  /comments   (O)
❌ /todo   /user   /getUser    (X)

③ 특정 하나는 id로 지정

GET    /todos        → 할 일 전체 목록
GET    /todos/1      → 1번 할 일 하나
PATCH  /todos/1      → 1번 할 일 수정
DELETE /todos/1      → 1번 할 일 삭제

관계가 있는 데이터의 주소

Day 2에서 "사용자 1명 → 할 일 여러 개"(1:N) 관계를 만들었죠. 주소로는 이렇게 표현합니다.

GET /users/1/todos    → 1번 사용자의 할 일 목록

4. 요청과 응답 — 무엇을 주고받나

API 한 줄은 요청(보내는 것) 과 응답(받는 것) 으로 이뤄집니다.

예시: 할 일 만들기

요청과 응답: 프론트가 POST /todos를 보내면 서버가 201 Created로 응답

요청 (프론트 → 서버)

POST /todos
{
  "title": "장보기",
  "due_date": "2026-01-15"
}

응답 (서버 → 프론트)

201 Created
{
  "id": 5,
  "title": "장보기",
  "is_done": false,
  "due_date": "2026-01-15",
  "user_id": 1
}

상태 코드 — 응답의 "결과 신호"

서버는 숫자로 결과를 알려줍니다. 자주 보는 것만:

코드뜻
200성공 (조회·수정)
201생성 성공
400요청이 잘못됨 (입력값 오류)
401로그인 안 됨
403권한 없음
404찾는 게 없음
500서버 에러 (코드 버그)

💡 4xx는 "네(손님) 잘못", 5xx는 "내(서버) 잘못"이라고 외우면 쉽습니다.

5. 실습 — 내 프로젝트 API 명세서 작성

ERD의 각 테이블마다 보통 CRUD 5종 세트가 나옵니다. 아래 표를 채우세요.

🛠 실습 템플릿

# 내 프로젝트 API 명세서 v0.1

## [리소스명: ______] 예) todos

| 메서드 | 주소 | 하는 일 | 로그인 필요? |
|--------|------|---------|-------------|
| GET    | /______       | 목록 조회 | |
| GET    | /______/:id   | 하나 조회 | |
| POST   | /______       | 생성      | |
| PATCH  | /______/:id   | 수정      | |
| DELETE | /______/:id   | 삭제      | |

## 주요 요청/응답 예시 (POST 1개만이라도)

요청:
POST /______
{
  "____": "____",
}

응답:
201 Created
{
  "id": 1,
  ...
}

✍️ 막힐 때 보세요

API가 몇 개나 필요하죠? → 테이블 1개당 CRUD 5개가 기본입니다. 테이블 3개면 약 15개. 다 만들 필요 없고, 핵심 기능에 쓰이는 것부터 설계하세요.

로그인 같은 건 어느 메서드죠? → 로그인은 "세션을 생성"하는 거라 보통 POST /auth/login 으로 둡니다. 인증은 Day 9에서 자세히 다룹니다.

쿼리로 거르는 건요? (검색·필터) → 주소 뒤에 ?로 붙입니다. 예: GET /todos?is_done=false (완료 안 된 것만). 지금은 몰라도 됩니다.

6. 오늘의 체크리스트

  • API가 "화면과 서버의 약속된 주문 방법"임을 이해했다
  • GET/POST/PATCH/DELETE의 역할을 구분할 수 있다
  • REST 주소 규칙(명사·복수형·id)을 안다
  • 상태 코드 200/201/400/401/404/500의 뜻을 안다
  • 내 프로젝트 API 명세서 초안을 작성했다 ← 가장 중요!

7. 다음 시간 예고

Day 4 — Git/GitHub + 개발환경 세팅

  • 드디어 실제 코드를 작성할 환경을 갖춥니다
  • Git 협업 플로우 / GitHub 저장소 생성 / 프로젝트 초기 세팅
  • 준비물: 지금까지 만든 명세서 + ERD + API 명세

📌 숙제: API 명세서에서 "이번 첫 스프린트에 실제로 만들 API 3개"에 ⭐ 표시해 오세요.

API 명세서는 프론트와 백엔드가 따로 일해도 만나는 지점입니다. 이 메뉴판이 정확하면 AI에게 시키는 것도 명확해집니다. 📋