← 이전: Week 11 목차 다음: Week 13 →

Week 12: Detailed Design

📌 학습 목표

📚 주요 내용

1. RESTful API 설계 원칙

1.1 REST 기본 개념

REST (Representational State Transfer):

6가지 제약 조건:

  1. Client-Server: 역할 분리
  2. Stateless: 무상태성 (각 요청은 독립적)
  3. Cacheable: 캐시 가능
  4. Uniform Interface: 일관된 인터페이스
  5. Layered System: 계층화된 시스템
  6. Code on Demand (선택): 서버가 클라이언트 실행 코드 전송 가능

1.2 리소스 네이밍 규칙

기본 원칙:

좋은 예시:

나쁜 예시:

1.3 HTTP 메서드 사용

Method 용도 Idempotent Safe
GET 조회 (Read) O O
POST 생성 (Create) X X
PUT 전체 수정 (Update) O X
PATCH 부분 수정 (Partial Update) X X
DELETE 삭제 (Delete) O X

Idempotent (멱등성): 동일한 요청을 여러 번 수행해도 결과가 동일
Safe (안전성): 리소스를 변경하지 않음

2. API 엔드포인트 카탈로그 (24개)

2.1 Users (사용자 관리)

# Method Endpoint Description
1 POST /api/v1/auth/register 사용자 회원가입
2 POST /api/v1/auth/login 로그인 (액세스 토큰 발급)
3 POST /api/v1/auth/refresh 토큰 갱신
4 POST /api/v1/auth/logout 로그아웃
5 GET /api/v1/users/{id} 사용자 프로필 조회
6 PATCH /api/v1/users/{id} 사용자 프로필 수정
7 DELETE /api/v1/users/{id} 사용자 탈퇴

2.2 Items (상품 관리)

# Method Endpoint Description
8 GET /api/v1/items 상품 목록 조회 (필터, 정렬, 페이징)
9 GET /api/v1/items/{id} 상품 상세 조회
10 POST /api/v1/items 상품 등록 (판매자/관리자)
11 PUT /api/v1/items/{id} 상품 전체 수정
12 PATCH /api/v1/items/{id} 상품 부분 수정 (예: 재고 수량)
13 DELETE /api/v1/items/{id} 상품 삭제

2.3 Cart (장바구니)

# Method Endpoint Description
14 GET /api/v1/cart 장바구니 조회
15 POST /api/v1/cart/items 장바구니에 상품 추가
16 PATCH /api/v1/cart/items/{itemId} 장바구니 상품 수량 변경
17 DELETE /api/v1/cart/items/{itemId} 장바구니 상품 삭제

2.4 Orders (주문)

# Method Endpoint Description
18 GET /api/v1/orders 주문 내역 조회
19 GET /api/v1/orders/{id} 주문 상세 조회
20 POST /api/v1/orders 주문 생성
21 PATCH /api/v1/orders/{id}/cancel 주문 취소

2.5 Reviews (리뷰)

# Method Endpoint Description
22 GET /api/v1/items/{itemId}/reviews 상품 리뷰 목록 조회
23 POST /api/v1/items/{itemId}/reviews 리뷰 작성
24 DELETE /api/v1/reviews/{id} 리뷰 삭제

3. Request/Response 스키마

3.1 Request 스키마 예시

POST /api/v1/auth/register

Request Body:

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd",
  "name": "홍길동",
  "phone": "010-1234-5678",
  "birthdate": "1990-01-01",
  "agreeTerms": true,
  "agreePrivacy": true,
  "agreeMarketing": false
}

Validation Rules:

3.2 Response 스키마 예시

Success Response (201 Created):

{
  "status": "success",
  "code": 201,
  "message": "회원가입이 완료되었습니다.",
  "data": {
    "userId": "u1234567890",
    "email": "user@example.com",
    "name": "홍길동",
    "createdAt": "2026-02-14T10:30:00Z"
  }
}

Error Response (400 Bad Request):

{
  "status": "error",
  "code": 400,
  "message": "입력값이 올바르지 않습니다.",
  "errors": [
    {
      "field": "email",
      "message": "이미 사용 중인 이메일입니다."
    },
    {
      "field": "password",
      "message": "비밀번호는 8자 이상이어야 합니다."
    }
  ],
  "timestamp": "2026-02-14T10:30:00Z",
  "path": "/api/v1/auth/register"
}

3.3 User 레코드 예시 (JSON)

{
  "userId": "u1234567890",
  "email": "user@example.com",
  "name": "홍길동",
  "phone": "010-1234-5678",
  "profileImageUrl": "https://cdn.example.com/profiles/u1234567890.jpg",
  "birthdate": "1990-01-01",
  "role": "customer",
  "status": "active",
  "agreeMarketing": false,
  "createdAt": "2026-01-01T09:00:00Z",
  "updatedAt": "2026-02-14T10:30:00Z",
  "lastLoginAt": "2026-02-14T08:00:00Z"
}

4. Error Handling 전략

4.1 HTTP 상태 코드

Success (2xx):

Client Error (4xx):

Server Error (5xx):

4.2 Error Response 표준 포맷

{
  "status": "error",
  "code": 400,
  "message": "사용자 친화적 에러 메시지",
  "errors": [
    {
      "field": "필드명",
      "message": "구체적인 오류 내용"
    }
  ],
  "errorCode": "ERR_USER_001",
  "timestamp": "2026-02-14T10:30:00Z",
  "path": "/api/v1/users",
  "requestId": "req-abc123def456"
}

4.3 Error Code 매핑

Error Code Description HTTP Status
ERR_AUTH_001 인증 토큰 만료 401
ERR_AUTH_002 인증 토큰 유효하지 않음 401
ERR_AUTH_003 권한 부족 403
ERR_USER_001 이메일 중복 409
ERR_USER_002 사용자 없음 404
ERR_ITEM_001 상품 재고 부족 422
ERR_ORDER_001 주문 취소 불가 상태 422
ERR_SYSTEM_001 내부 서버 오류 500

5. API Versioning (버전 관리)

5.1 버전 관리 전략

URI Versioning (권장):

장점: 명확하고 직관적, 캐싱 용이
단점: URI 변경

Header Versioning:

GET /api/users
Accept: application/vnd.myapi.v1+json

Query Parameter:

5.2 Breaking Change 관리

언제 버전 올려야 하나?:

Deprecated 처리:

6. Rate Limiting (속도 제한)

6.1 제한 전략

목적:

제한 기준:

6.2 제한 설정 예시

Free Tier:

Paid Tier:

6.3 Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1644836400

429 Too Many Requests:

{
  "status": "error",
  "code": 429,
  "message": "요청 제한을 초과했습니다. 1시간 후 다시 시도하세요.",
  "retryAfter": 3600
}

7. Zero Trust 보안 아키텍처

7.1 Zero Trust 개념

원칙: “신뢰하지 말고, 항상 검증하라 (Never Trust, Always Verify)”

핵심 요소:

  1. Identity Verification: 모든 요청에 대해 인증/인가 검증
  2. Least Privilege: 최소 권한 원칙
  3. Micro-Segmentation: 네트워크 세분화
  4. Continuous Monitoring: 지속적 모니터링 및 로깅

7.2 적용 전략

네트워크 계층:

애플리케이션 계층:

데이터 계층:

8. OAuth 2.0 및 OIDC 인증

8.1 OAuth 2.0 개요

정의:

주요 역할:

8.2 Grant Types (권한 부여 방식)

Authorization Code Flow (가장 안전, 웹 앱 권장):

  1. 사용자가 클라이언트 앱에서 로그인 요청
  2. Authorization Server로 리다이렉트
  3. 사용자 로그인 및 권한 동의
  4. Authorization Code 발급
  5. 클라이언트가 Code를 Access Token으로 교환
  6. Access Token으로 API 호출

Client Credentials Flow (서버 간 통신):

Implicit Flow (비권장, 보안 취약):

8.3 OIDC (OpenID Connect)

정의:

ID Token 구조:

{
  "iss": "https://auth.example.com",
  "sub": "u1234567890",
  "aud": "client-app-id",
  "exp": 1644836400,
  "iat": 1644832800,
  "name": "홍길동",
  "email": "user@example.com",
  "email_verified": true
}

8.4 구현 예시

POST /api/v1/auth/login

Request:

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd"
}

Response (200 OK):

{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "rt_abc123def456...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "user": {
      "userId": "u1234567890",
      "email": "user@example.com",
      "name": "홍길동",
      "role": "customer"
    }
  }
}

9. Token 관리

9.1 JWT (JSON Web Token) 구조

Header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload:

{
  "sub": "u1234567890",
  "role": "customer",
  "iat": 1644832800,
  "exp": 1644836400
}

Signature:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

9.2 Access Token vs Refresh Token

항목 Access Token Refresh Token
용도 API 호출 인증 Access Token 갱신
유효 기간 짧음 (15분~1시간) 김 (7일~30일)
저장 위치 메모리 또는 SessionStorage HttpOnly Cookie (권장)
노출 위험 높음 (짧은 수명으로 완화) 낮음 (보안 저장)

9.3 Token Refresh Flow

  1. 클라이언트가 API 호출 (Access Token 첨부)
  2. 서버가 401 Unauthorized 응답 (Token Expired)
  3. 클라이언트가 Refresh Token으로 갱신 요청
  4. 서버가 새로운 Access Token 발급
  5. 재시도

POST /api/v1/auth/refresh

Request:

{
  "refreshToken": "rt_abc123def456..."
}

Response (200 OK):

{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}

9.4 Token Revocation (토큰 무효화)

로그아웃 시:

10. 암호화 (Encryption)

10.1 데이터 암호화

at Rest (저장 시):

in Transit (전송 시):

10.2 비밀번호 해싱 예시

bcrypt (Node.js):

const bcrypt = require('bcrypt');
const saltRounds = 10;

// 해싱
const hashedPassword = await bcrypt.hash('SecureP@ssw0rd', saltRounds);
// 결과: $2b$10$abcdefghijklmnopqrstuvwxyz...

// 검증
const isMatch = await bcrypt.compare('SecureP@ssw0rd', hashedPassword);
// true

10.3 민감 정보 암호화 (AES-256)

암호화 대상:

Key 관리:

🛠️ 실습 과제

과제 1: API 엔드포인트 카탈로그 작성

과제 2: Request/Response 스키마 작성

과제 3: Error Handling 전략 수립

과제 4: 인증 플로우 설계

📖 참고 자료

🔄 복습 체크리스트

📝 다음 주 예습

Week 13: UI/UX Design & Implementation

← 이전: Week 11 목차 다음: Week 13 →

Last Updated: 2026-02-14