[UMC_study] Web API 디자인 모범 사례

https://learn.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

Web API 디자인 모범 사례 - Azure Architecture Center

 

다음 글을 읽고 내용을 요약해봤습니다.

 

RESTful 웹 API 디자인 핵심 요약

1. RESTful API의 기본 개념

• 자원(Resource) 중심 설계: 모든 것을 명사 형태의 자원(URI)으로 표현합니다. (/create-order (X) -> /orders (O))
• 균일한 인터페이스(Uniform Interface): GET, POST, PUT, DELETE 등 표준 HTTP 메서드를 사용하여 자원에 대한 작업을 수행합니다.
• 상태 비저장(Stateless): 각 요청은 독립적으로 처리되어야 하며, 서버는 클라이언트의 이전 상태를 저장하지 않습니다.
• HATEOAS(Hypermedia as the Engine of Application State): 응답에 관련된 다른 자원으로의 링크를 포함하여 API의 탐색 가능성을 높입니다.

---

2. 리소스 URI 설계 규칙

• 명사 사용: URI는 자원을 나타내므로 동사가 아닌 명사를 사용합니다.
• 복수 명사 사용: 컬렉션(자원 모음)을 나타내는 URI에는 복수 명사를 사용합니다. (예: /customers, /orders)
• 단순하고 직관적인 구조: /customers/5/orders와 같이 계층 구조를 활용하되, 너무 깊어지지 않도록 주의합니다.
• 내부 구조 미러링 금지: 데이터베이스 테이블 구조를 API에 그대로 노출하지 않습니다.

---

3. HTTP 메서드의 올바른 사용

메서드	컬렉션 (/orders)	개별 항목 (/orders/1)	특징
GET	모든 주문 목록 조회	특정 주문 상세 조회	자원 조회
POST	새 주문 생성	(오류 또는 미사용)	자원 생성 (서버가 URI 할당)
PUT	모든 주문 일괄 업데이트	특정 주문 전체 수정/대체	자원 전체 수정 (멱등성 보장)
PATCH	(미사용)	특정 주문 부분 수정	자원 부분 수정
DELETE	모든 주문 삭제	특정 주문 삭제	자원 삭제

 

---

4. 고급 데이터 처리 기법

• 페이징(Pagination): limit(개수)와 offset(시작점) 쿼리 파라미터를 사용하여 대규모 데이터셋을 나눠서 반환합니다.
• 필터링(Filtering) 및 정렬(Sorting): 쿼리 파라미터(예: ?status=shipped, ?sort=price)를 이용해 클라이언트가 원하는 데이터만 정제하여 볼 수 있게 합니다.
• 부분 응답(Partial Response): fields 파라미터(예: ?fields=id,name)를 통해 필요한 필드만 요청하여 네트워크 부하를 줄입니다.
• 비동기 처리: 오래 걸리는 작업은 즉시 응답하지 않고, 202 Accepted 상태 코드를 반환한 뒤 상태를 확인할 수 있는 URI를 제공합니다.

---

5. API 버전 관리 전략

웹 API가 변경될 때 기존 클라이언트의 호환성을 유지하기 위해 버전을 관리합니다.

• URI 버전 관리: /v1/orders
• 쿼리 문자열 버전 관리: /orders?version=1
• 헤더 버전 관리: Custom-Header: api-version=1
• 미디어 타입 버전 관리: Accept: application/vnd.contoso.v1+json (HATEOAS와 가장 잘 어울리는 방식)

---

6. 기타 중요 고려사항

• 다중 테넌시: 여러 고객(테넌트)이 하나의 API를 공유할 때, 하위 도메인, URI 경로, HTTP 헤더 등을 통해 테넌트를 명확히 구분하여 설계합니다.
• 분산 추적: Correlation-ID 같은 헤더를 사용하여 마이크로서비스 환경에서 요청의 흐름을 추적하고 디버깅을 용이하게 합니다.
• OpenAPI(Swagger): API의 명세를 표준화하여 문서 자동화, 클라이언트 코드 생성 등에 활용하는 '계약 우선(Contract-First)' 접근 방식을 권장합니다.