실용적인 API 설계 원칙

API는 다른 소프트웨어가 어떤 방식으로 생각해도 되는지에 대한 약속이다. 좋은 설계는 예외를 줄이고 안전한 경로를 분명하게 만든다.

도메인 어휘를 모델링하기

리소스 이름은 내부 테이블이 아니라 사용자가 알아볼 수 있는 개념에서 가져온다. 일관된 명사, 동사, 식별자는 올바른 요청을 만드는 데 필요한 문서량을 줄인다.

실패를 구체적으로 만들기

프로그램을 위한 안정적인 오류 코드, 사람을 위한 간결한 메시지, 입력을 고칠 수 있을 때 필요한 필드 단위 세부 정보를 반환한다. 공개 경계를 통해 구현 흔적이 새어 나가지 않게 한다.

{
  "code": "invalid_delivery_window",
  "message": "배송 가능 시간이 시작되기 전에 끝납니다.",
  "field": "deliveryWindow.end"
}

호환성을 보존하기

기존 필드를 제거하거나 다시 정의하기 전에 선택 필드를 먼저 추가한다. 관대한 읽기 방식과 명확한 지원 중단 기간은 클라이언트가 동시 릴리스 없이도 이동할 수 있게 해 준다.

멱등성을 설계에 포함하기

재시도될 수 있는 변경 작업은 멱등성 키를 받는다. 서버는 그 키에 결과를 저장하고, 네트워크 타임아웃으로 재시도가 발생하면 같은 결과를 반환한다.