API 계약
계약은 제어할 수 없고 고칠 수 없는 코드에 대한 약속입니다. 이것이 API 변경이 내부 리팩토링과 다른 점입니다: 잘못 변경했을 때의 비용은 다른 사람이, 여러분이 선택하지 않은 시점에 부담하게 됩니다.
설계
리소스 이름을 명사로 짓고 메서드가 동작(동사)을 전달하도록 합니다. 현재 화면에 표시되는 것을 모델링하지 말고, 실제 사물(데이터)을 모델링하세요. 오늘의 UI를 기준으로 만든 페이로드는 다음 재설계 시점에 맞지 않게 됩니다.
노출할 내용을 신중히 결정하세요. 반환하는 모든 필드는 계속 반환해야 하는 필드입니다. 내부 식별자, 행 버전, 구현 세부 정보는 스키마를 호출자의 코드 속으로 새어 나가게 하고 거기에 고정시킵니다.
호출자가 재시도할 수 있는 모든 작업(네트워크를 통해 접근 가능한 모든 작업)은 멱등(idempotent)하게 만드세요. 생성하거나 요금을 부과하는 작업에는 호출자에게 멱등성 키를 제공하여 타임아웃 후 재시도가 중복을 발생시키지 않도록 하세요.
일관된 오류 모델을 반환하세요: 안정적인 기계 판독 가능 코드, 사람이 읽을 수 있는 메시지, 그리고 유효성 검사 실패 시 관련 필드를 포함합니다. 호출자는 코드를 기준으로 분기 처리하므로 코드는 계약의 일부입니다. 코드를 변경하는 것은 형태는 그대로이더라도 호환성을 깨는 변경입니다.
모든 목록은 첫 번째 버전부터 페이지네이션하세요. 모든 것을 반환하는 엔드포인트는 테이블이 커질 때까지는 작동하다가 가장 많은 데이터를 가진 고객에게서 실패합니다. 동시에 행이 삽입되는 경우 오프셋보다는 커서를 선호하세요.
호출자를 깨는 변경
스키마 언어가 허용하는 것과 관계없이 다음은 호환성을 깨는 변경입니다:
- 필드, 엔드포인트, 메서드 또는 열거형 값의 제거 또는 이름 변경.
- 선택적인 요청 필드를 필수로 만들거나, 필드가 허용하는 값의 범위를 좁히는 것.
- 타입 변경(정수를 문자열로, 단일 값을 리스트로 변경하는 것 포함).
- 기존 필드의 이름과 타입은 유지하면서 의미를 변경하는 것 — 가장 나쁜 유형으로, 명시적으로 실패하지 않고 데이터가 조용히 손상되기 때문.
- 요청에 새로운 필수 필드를 추가하는 것.
- 기존 조건에 대한 오류 코드 또는 HTTP 상태를 변경하는 것.
- 기본값을 강화하거나, 필드가 생략되었을 때의 동작을 변경하는 것.
안전한 변경: 선택적 요청 필드 추가, 응답 필드 추가, 새 엔드포인트 또는 메서드 추가, 열거형 값 추가(단, 모든 소비자가 이미 알 수 없는 값을 허용하는 경우에만 — 추정하지 말고 반드시 확인하세요).
protobuf에서는 필드 태그를 재사용하거나 번호를 다시 매기지 말고, 필드를 제거할 때는 태그와 이름을 예약(reserve)하세요. 재사용된 태그는 이전 데이터를 새 필드로 디코딩하여 조용히 손상시킵니다.
계약을 안전하게 변경하기
제거하기 전에 추가하고, 최소 한 번의 릴리스 동안 둘 다 작동하게 유지하세요:
- 새 필드나 메서드를 기존 것 옆에 추가합니다.
- 둘 다 쓰고, 새 것을 읽을 때는 예전 것으로 대체(fallback)합니다.
- 소비자를 마이그레이션하고 각각이 이동했는지 확인합니다.
- 이후 릴리스에서 이전 경로를 제거합니다.
리소스의 의미가 실제로 변경될 때만 버전을 부여하고, 매 추가마다 버전을 만들지 마세요. 변경마다 버전을 만들면 유지해야 할 표면이 기하급수적으로 늘어납니다.
배포 순서
생성된 코드와 서버는 별도로 배포되며, 그 사이에 장애가 발생할 수 있습니다. 먼저 두 형태를 모두 허용하는 쪽을 먼저 배포하세요: 생산자가 새 필드를 내보내기 전에 소비자가 새 필드를 받아들이고, 호출자가 새 요청을 보내기 전에 생산자가 새 요청을 받아들입니다.
스키마가 게이트웨이, 프록시 또는 생성된 클라이언트를 통해 공유될 때는 경로상의 모든 구성 요소를 재생성하고 재배포해야 합니다. 서비스에 추가되었지만 그 앞 계층에는 추가되지 않은 필드는 호출자에게 도달하기 전에 사라지며, 서비스 자체 테스트는 이를 감지하지 못합니다.
검증
형태를 변경하기 전에 실제 소비자를 확인하세요 — 계약 문서를 신뢰하기보다 실제 호출자 코드를 grep 하세요.
계약 자체를 테스트하세요: 직렬화된 형태를 단언하는 테스트는 핸들러에 대한 단위 테스트로는 완전히 놓칠 수 있는 우발적인 이름 변경을 잡아냅니다.