API 계약은 엔드포인트 주소가 아니라 서로 기대하는 입력과 출력입니다

API 계약은 서버와 클라이언트가 같은 필드, 상태 코드, 오류 의미를 기대하게 만드는 약속입니다.

/users/1이라는 주소가 그대로여도 응답 필드가 사라지거나 타입이 바뀌면 클라이언트는 깨질 수 있습니다.
상태 코드 의미가 바뀌어도 마찬가지입니다.
API 계약은 주소가 아니라 입력, 출력, 오류, 시간 제한, 정렬, 페이지네이션까지 포함합니다.

클라이언트는 문서가 아니라 실제 응답에 맞춰집니다

문서에는 optional이라고 적혀 있어도 클라이언트가 매번 값이 있다고 믿고 만들었으면 사실상 required가 됩니다.
반대로 서버가 쓰지 말라고 한 필드를 클라이언트가 이미 쓰고 있을 수도 있습니다.
계약은 문서와 코드 사이의 합의입니다.
그래서 실제 사용 로그와 타입 검사가 같이 필요합니다.

깨지는 변경과 안 깨지는 변경을 구분합니다

응답에 새 필드를 추가하는 건 대체로 안전합니다.
필드를 삭제하거나 타입을 바꾸거나 enum 값을 바꾸는 건 위험합니다.
정렬 기본값을 바꾸는 것도 사용자에게는 동작 변경일 수 있습니다.
API 변경 전에는 “기존 소비자가 이 변경을 모른 채로 살아남는가”를 물어야 합니다.

계약 테스트는 양쪽의 기억을 맞춥니다

서버 테스트만으로는 부족할 때가 있습니다.
클라이언트가 기대하는 응답 예시를 계약 테스트로 고정하면 서버 리팩터 중에 실수로 모양을 바꾸는 일을 줄일 수 있습니다.
API 계약은 친절한 문서가 아니라 변경 비용을 낮추는 안전장치입니다.

마지막으로 확인할 것은 하나입니다.
이 개념을 외웠는지가 아니라, 실패했을 때 어떤 상태가 남는지 설명할 수 있는지입니다.