22장. API 계약 리뷰 실전

예약 생성 API에는 idempotency key, tenant context, client deadline, 상태 코드, 오류 body, retry 가능성, version을 정의한다. 500 하나로 모든 실패를 표현하면 클라이언트가 안전하게 재시도할 수 없다. validation, conflict, dependency timeout, 처리 중, 영구 실패를 업무 의미로 나눈다.

POST /v1/reservations
Idempotency-Key: <UNIQUE_COMMAND_KEY>
If-Match: "slot-version-7"

201 Created | 409 SlotTaken | 202 Processing | 503 RetryableDependency

리뷰어는 같은 키에 다른 body, 응답 유실, 202 뒤 조회, 클라이언트 취소, API version 혼재를 주입한다. 오류에는 안정된 machine code와 correlation ID를 두고 stack·SQL·내부 host를 넣지 않는다. 계약은 OpenAPI 파일만이 아니라 timeout·retry·권한·데이터 보존까지 포함한다.