API 디자인 리뷰
개요
클라이언트 관점에서 API를 판단합니다: 예측 가능한 이름, 정직한 상태 코드, 통일된 오류 형식, 안전한 재시도, 그리고 예상치 못한 호환성 파괴 변경이 없어야 합니다. 모든 발견 사항은 구체적인 라우트를 가리키며 수정된 디자인을 제시합니다.
방법
- 인벤토리. 모든 엔드포인트를
METHOD /path → 상태 코드 → 요청/응답 형식으로 나열합니다. 라우트, 컨트롤러, OpenAPI 파일 및 DTO를 읽습니다. - 각 엔드포인트를 아래 규칙에 따라 확인합니다.
- API 전체를 확인합니다: 단일 선택보다 엔드포인트 간 일관성이 더 중요합니다.
- 변경 사항: diff를 검토하는 경우, 이전 계약과 새 계약을 비교하고 기존 클라이언트를 손상시키는 모든 것을 표시합니다.
- 보고서는 아래 출력 계약 형식으로 작성합니다.
규칙
| 영역 | 규칙 |
|---|---|
| 리소스 | 복수 명사, 동사 사용 금지: POST /orders, /createOrder 아님. 진정한 소유 관계에만 중첩: /users/{id}/orders. |
| 메서드 | GET은 읽기이며 안전(safe)합니다. POST는 생성합니다. PUT은 교체합니다. PATCH는 부분 업데이트합니다. DELETE는 제거합니다. GET에서 상태를 절대 변경하지 마세요. |
| 상태 코드 | 200 OK, 201 Created (+ Location), 204 No Content, 400 잘못된 입력, 401 인증되지 않음, 403 허용되지 않음, 404 없음, 409 충돌, 422 유효성 검사, 429 속도 제한, 5xx는 서버 오류 전용. {"error": ...}와 함께 200을 절대 사용하지 마세요. |
| 오류 | 모든 곳에서 하나의 형식, 예: RFC 9457: { "type", "title", "status", "detail", "errors": [{ "field", "message" }] }. 응답에 스택 트레이스나 SQL을 포함하지 마세요. |
| 네이밍 | JSON 필드에 하나의 케이싱(camelCase 또는 snake_case), 일관된 ID, ISO 8601 UTC 타임스탬프, 금액은 정수 최소 단위 또는 소수 문자열 + 통화로 표시. |
| 컬렉션 | 모든 목록에 페이지네이션 적용(대용량 또는 자주 변경되는 데이터에는 커서 선호), 페이지 크기 제한, 다음 커서 또는 링크 반환. 필터링과 정렬은 쿼리 파라미터로 처리. |
| 멱등성 | 결제, 주문 또는 이메일을 생성하는 재시도된 POST는 Idempotency-Key를 받아야 합니다. PUT과 DELETE는 설계상 멱등적입니다. |
| 버전 관리 | 명확한 전략(/v1 경로 또는 헤더). 호환성 파괴 변경은 새 버전으로 이동합니다. |
| 호환성 파괴 변경 | 필드 제거 또는 이름 변경, 타입 변경, 선택적 입력을 필수로 변경, 상태 코드 또는 오류 형식 변경, 유효성 검사 강화. |
| 보안 | 모든 비공개 라우트에 인증, 객체 수준 소유권 확인, 인증 및 비용이 많이 드는 라우트에 속도 제한, URL에 민감한 데이터 없음. |
| 성능 | 무제한 응답 금지, 무거운 객체에 fields 또는 희소 응답 지원, 캐시 가능한 GET에 ETag 또는 Cache-Control 사용. |
출력 계약
다음으로 시작: N개 엔드포인트 검토, M개 발견 사항(X개 호환성 파괴). 그런 다음 영향도가 높은 순서로:
### [호환성 파괴 | 높음 | 중간 | 낮음] 제목
- 엔드포인트: METHOD /path (파일:줄)
- 문제: 클라이언트가 겪는 현상
- 수정: 수정된 라우트, 상태 코드 또는 JSON 형식
짧은 일관성 요약(케이싱, 오류 형식, 페이지네이션, 버전 관리: 일관됨 또는 불일치)으로 마무리하고, 처음부터 설계하는 경우 제안된 엔드포인트 테이블을 추가합니다.
흔한 실수
- 엔드포인트를 하나씩 검토하면서 둘 사이의 케이싱이나 오류 형식 불일치를 놓치는 경우.
- 하위 호환 가능한 추가만으로 충분할 때 재설계를 권장하는 경우.
- 서버 코드가 여전히 작동한다는 이유로 변경을 안전하다고 판단하는 경우: 기존 클라이언트가 보내고 기대하는 내용을 확인하세요.
- 신중하게 결정하지 않고 유효성 검사 오류에 500을 사용하거나 권한 실패에 404를 사용하는 경우.