[UMC/시니어 미션#4]

✏️  Soft Delete란?

🔹 정의

• Soft Delete는 데이터를 실제로 삭제하지 않고, '삭제된 것처럼 표시'만 하는 방식입니다.
• 데이터베이스에는 그대로 존재하지만, 일반 사용자에겐 보이지 않도록 처리합니다.
• 주로 deleted_at 컬럼에 삭제 시각을 저장하거나, is_deleted 같은 Boolean 필드로 표시합니다.

🔹 장점

• 복구 가능: 실수로 삭제한 데이터를 나중에 복구할 수 있음
• 감사 및 기록 유지: 삭제 이력 관리 가능
• 데이터 무결성 유지: 참조 관계가 복잡한 경우 유리

🔹 Soft Delete에 적합한 HTTP Method?

• 보통 **DELETE*를 사용하지만, 실제로 삭제하지 않고 soft delete 처리만 합니다.
• 때때로 PATCH 또는 **POST*를 사용하여 is_deleted 값을 변경하는 방식도 사용됩니다.

 

 

✏️  컨트롤 URI (Control URI)

🔹 정의

• 일반적인 CRUD URI 외에, 특정 동작을 수행하기 위한 URI를 말합니다.
• 보통 명사(Resource)가 아니라 동사(Action) 형태로 구성됩니다.

🔹 사용 예시

• 특정 기능이나 상태 변경 등, 일반 CRUD로 표현하기 어려운 작업에 사용
• 예:
  • /users/123/activate → 사용자 계정 활성화
  • /orders/456/cancel → 주문 취소
  • /products/789/publish → 상품 공개 처리

🔹 언제 사용하는가?

• 단순한 Create, Read, Update, Delete 외의 특정 기능을 수행해야 할 때
• 비즈니스 로직 중심의 API 설계가 필요한 경우

 

✏️ RESTful 웹 API 디자인 모범 사례 (상세 정리)

1. RESTful 웹 API 기본 원칙

• 플랫폼 독립성
  • HTTP 프로토콜 사용, JSON/XML 같은 표준 데이터 형식 지원
  • 클라이언트-서버 구조에서 서로의 내부 구현을 몰라도 동작
• 느슨한 결합
  • 서버는 클라이언트에 맞추지 않고 독립적으로 발전 가능
  • 클라이언트는 서버 내부 로직을 알 필요 없음
• 균일한 인터페이스
  • GET, POST, PUT, PATCH, DELETE 같은 표준 HTTP 메서드 활용
• 상태 비저장(Stateless)
  • 각 요청은 독립적 → 서버에 세션 저장 없음
  • 상태 정보는 리소스 자체에 저장
• HATEOAS
  • 응답 본문에 관련 리소스 링크 포함 → API 탐색 가능

2. 리소스(URI) 설계 원칙

• 명사 기반: /create-order → /orders
• 복수형 사용: /orders, /customers
• 리소스 간 관계 표현
  • 고객의 모든 주문: /customers/5/orders
  • 특정 주문의 고객: /orders/99/customer
• 중첩 최소화
  • /customers/1/orders/99/products
  • /customers/1/orders + /orders/99/products
• 데이터베이스 스키마 노출 금지
  • DB 테이블 그대로 노출하지 말고, 비즈니스 개념 중심으로 설계

3. HTTP 메서드 설계

3.1 메서드 활용 규칙

메서드 컬렉션(/customers) 항목(/customers/1)

GET	고객 목록 조회	특정 고객 조회
POST	새 고객 생성	❌ (잘못된 패턴)
PUT	일괄 업데이트	전체 교체 (있으면 수정, 없으면 생성)
PATCH	❌	일부 속성 업데이트
DELETE	전체 삭제	특정 고객 삭제

 

3.2 상태 코드 사용 예

• GET: 200(OK), 204(No Content), 404(Not Found)
• POST: 201(Created), 400(Bad Request), 405(Method Not Allowed)
• PUT: 200(OK), 201(Created), 204(No Content), 409(Conflict)
• PATCH: 200(OK), 400(Bad Request), 409(Conflict), 415(Unsupported Media Type)
• DELETE: 204(No Content), 404(Not Found)

3.3 PATCH 방식

• JSON Merge Patch (RFC 7396) → 단순, null로 필드 삭제 가능
• JSON Patch (RFC 6902) → 작업 단위(add, remove, replace, test 등), 더 유연

4. 리소스 표현 (Representation)

• 미디어 타입
  • JSON → application/json
  • XML → application/xml
• Content-Type & Accept 헤더
  • 요청 본문 형식 지정 → Content-Type
  • 클라이언트가 원하는 응답 형식 지정 → Accept
• 에러 처리
  • 지원하지 않는 형식 → 415 Unsupported Media Type
  • 응답 불가능 → 406 Not Acceptable

5. 성능 및 기능 확장

5.1 비동기 처리

• 장기 작업 → 즉시 응답: 202 Accepted
• 응답에 상태 엔드포인트 포함
• 완료 시: 303 See Other + 새 리소스 URI 반환

5.2 페이징 & 필터링

• 페이징: GET /orders?limit=25&offset=50
• 필터링: GET /orders?status=shipped&minCost=100
• 정렬: ?sort=price
• 필드 선택: ?fields=id,name
• 보안 주의: 클라이언트가 불필요한 내부 필드 접근 못하게 제한

5.3 부분 응답 (대형 파일 등)

• HEAD 요청 → 리소스 크기 확인
• Range 헤더 → 206 Partial Content 응답
• 예: 이미지 일부만 다운로드

6. 버전 관리 전략

• URI 버전 관리
  • /v2/customers/3
  • 단순하지만 URI와 링크가 복잡해짐
• 쿼리 문자열 버전 관리
  • /customers/3?version=2
• 헤더 버전 관리
  • Custom-Header: api-version=2
• 미디어 타입 버전 관리 (권장)
  • Accept: application/vnd.contoso.v2+json
  • HATEOAS와 잘 맞음

7. 다중 테넌시 (Multi-Tenancy)

• 하위 도메인 기반
  • tenant1.api.com/orders/3
• 헤더 기반
  • X-Tenant-ID: tenant1
• URI 경로 기반
  • /tenants/tenant1/orders/3
• 주의: 캐시/보안 문제 발생 가능 → 반드시 테넌트 격리 설계 필요

8. 모니터링 & 추적 (Observability)

• 요청에 추적 헤더 포함
  • Correlation-ID, Trace-ID, Request-ID
• API 응답에도 같은 ID 반환 → 분산 추적 가능

9. 성숙도 모델 (Richardson Maturity Model, RMM)

• Level 0: 모든 요청을 POST 한 URI로 (SOAP 스타일)
• Level 1: 리소스 URI 도입
• Level 2: HTTP 메서드 사용 (대부분의 API)
• Level 3: HATEOAS 적용 → 진정한 RESTful