이 lesson 을 다 읽고 나면 아래 3가지를 자신 있게 할 수 있습니다.

• ▸✅ REST 6원칙 + Stateless · Cacheable · Uniform Interface
• ▸✅ REST vs GraphQL vs gRPC 선택
• ▸✅ OpenAPI (Swagger) 명세 작성

학습 목표를 체크리스트로 두고 다 답할 수 있게 되면 lesson 을 닫으세요.

REST (Roy Fielding, 2000) — Representational State Transfer

6 원칙:
1. Client-Server — 분리
2. Stateless — 서버가 상태 X (각 요청 독립)
3. Cacheable — 응답 캐시 가능
4. Uniform Interface — 표준 메서드 (GET·POST·PUT·DELETE)
5. Layered — 클라이언트는 직접 vs 프록시 통과 모름
6. Code on Demand (선택) — JS 다운로드 가능

RESTful URL 설계:

좋은 응답 설계:

{
  "data": { "id": 42, "name": "홍길동" },
  "meta": { "version": "v1", "timestamp": "2025-..." }
}

// 에러
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "사용자를 찾을 수 없습니다",
    "details": { "id": 42 }
  }
}

버저닝 3가지:

• ▸URL: /v1/users (가장 흔함)
• ▸헤더: Accept: application/vnd.api+json;version=1
• ▸쿼리: /users?version=1

HATEOAS (RESTful 의 끝판왕):

• ▸응답에 다음 가능한 액션 링크 포함
• ▸잘 안 씀 (실용성 ↓)

REST vs GraphQL vs gRPC — 3 패러다임:

GraphQL — Facebook (2015):

query {
  user(id: 42) {
    name
    email
    orders(last: 5) {
      id
      total
    }
  }
}

• ▸한 요청에 필요한 것만 받음
• ▸백엔드 1개로 다양한 클라이언트 (웹·모바일·앱)
• ▸단점: 캐싱·rate limit 복잡

gRPC — Google (2015):

• ▸Protobuf 스키마 정의:

service UserService {
  rpc GetUser (UserId) returns (User);
  rpc StreamUsers (Filter) returns (stream User);
}
message User { int64 id = 1; string name = 2; }

• ▸코드 자동 생성 (Java·Go·Python·...)
• ▸bidirectional streaming
• ▸내부 MSA 표준 (Google·Netflix·Uber)
• ▸브라우저는 gRPC-Web 필요

언제 무엇을:

• ▸🟢 REST: 일반 외부 API·모바일·웹
• ▸🟢 GraphQL: 복잡한 UI·다양한 클라이언트
• ▸🟢 gRPC: 내부 MSA·실시간 스트리밍

JSON (JavaScript Object Notation, 2001) — 데이터 교환 표준:

{
  "name": "홍길동",
  "age": 28,
  "hobbies": ["코딩", "독서"],
  "address": {
    "city": "서울",
    "zip": "06164"
  },
  "active": true,
  "registered_at": null
}

자료형:

• ▸string: "text" (UTF-8)
• ▸number: 42, 3.14, 1e10 (정수·실수 구분 X)
• ▸boolean: true, false
• ▸null
• ▸array: [1, 2, 3]
• ▸object: {"key": "value"}

함정:

• ▸❌ 주석 X (JSON5·JSONC 는 별개)
• ▸❌ trailing comma X
• ▸❌ 작은따옴표 X (큰따옴표만)
• ▸❌ undefined X
• ▸✅ 정수 정밀도: JS Number 는 2^53 이하만 안전 → 큰 ID 는 string 권장

API 호출 흐름 (브라우저 → DB까지):

1. JS: fetch('/api/users/42')
   └─ 브라우저 fetch API

2. 브라우저:
   - DNS 조회 (codemaster40.com → IP)
   - TCP 3-way + TLS 핸드셰이크
   - HTTP/2 또는 HTTP/3 요청 전송

3. CDN (CloudFront 등):
   - 정적 캐시 hit ? → 즉시 응답
   - miss → origin 으로

4. 로드 밸런서 (ALB·Nginx):
   - 어느 서버로? (round-robin·least-conn)
   - SSL termination (TLS → 평문 내부)

5. 애플리케이션 서버 (Node·Spring):
   - 미들웨어 (인증·로깅·rate limit)
   - 라우터 → 컨트롤러
   - 비즈니스 로직

6. 캐시 (Redis):
   - hit → 즉시 반환
   - miss → DB 로

7. 데이터베이스 (Postgres·MySQL):
   - 쿼리 실행 (EXPLAIN 결과대로)
   - 결과 → 캐시 저장 → 응답

8. 역순으로 응답
   DB → App → LB → CDN → 브라우저 → JS

각 단계가 최적화 포인트 — 1단계 느리면 전체 느림.

이 lesson 의 개념을 알면 AI 에게 구체적으로 지시할 수 있습니다. 막연한 "고쳐줘" 가 아니라 어휘를 가진 요청 — 그게 토큰 절약의 출발점입니다.

• ▸"이 REST API 를 GraphQL 로 변환했을 때 장단점 비교해줘"
• ▸"이 API 에 OpenAPI (Swagger) 명세 작성해줘"

왜 이게 토큰을 줄이나

개념을 모를 땐 AI 답변을 받고도 "그게 뭐예요?" 를 다시 물어야 합니다. 그 "다시 물음" 이 토큰을 잡아먹습니다. 개념 한 번 익혀두면 대화가 한 번에 끝납니다.