주문 웹사이트가 운영 시스템으로 새 주문을 보낸 상황을 생각해 보세요. 운영 시스템은 주문을 저장했지만 확인 응답은 웹사이트에 도착하지 않습니다. 웹사이트가 다시 시도해야 할까요? 두 번째 주문이 생길 수도 있을까요? 이 가상 사례는 API 계약이 비즈니스 운영에 중요한 이유를 보여줍니다. API 계약은 성공적인 시연만으로는 드러나지 않을 수 있는 경우까지 포함해 양쪽의 기대 동작을 설명합니다.
이 페이지의 내용
업무 흐름과 데이터 책임부터 정하세요
사용자 행동에서 확인된 결과까지 하나의 상호작용을 정리하세요. 주문 예시에서는 누가 주문 참조 번호를 생성하는지, 어떤 시스템이 주문 수락을 결정하는지, 고객이 어디서 상태를 확인하는지 파악해야 합니다. 요청 수신과 주문 수락은 서로 다른 이벤트일 수 있으므로 구분하세요. 각 정보를 어느 시스템이 변경할 수 있는지도 정해야 합니다. 두 시스템 모두 배송 주소를 편집할 수 있다면, 가장 최근 화면의 값을 기준값이라고 가정하는 대신 업데이트를 처리할 규칙이 계약에 필요합니다.
- 주문, 고객, 상태 정보의 책임 주체를 명시하세요.
- 사용자가 즉시 확인해야 할 결과를 정하세요.
- 수신 시스템이 나중에 보내야 할 업데이트를 파악하세요.
필드 정의를 구체적으로 작성하세요
메시지별 필수 정보, 허용 값, 정보가 없을 때의 의미를 문서화하세요. 가격에는 통화와 명확한 해석 기준이 필요하고, 타임스탬프에는 합의된 시간대 규칙이 필요합니다. 현실적인 주문 예시 하나를 사용해 규칙을 논의하세요. ‘취소됨’이 전체 주문인지 특정 품목인지, 빈 주소가 알 수 없음을 뜻하는지 의도적으로 삭제했음을 뜻하는지 확인하세요. 호출자별로 읽거나 수정할 수 있는 기록도 설명해야 합니다. 이런 결정은 명세와 애플리케이션 사용 경험 모두에 영향을 줍니다. 필드 이름을 맞추는 것만으로는 해결되지 않습니다.
반복 요청과 유용한 오류 처리를 명세하세요
주문 예시에서는 다음과 같은 규칙을 제안할 수 있습니다. 합의된 보존 기간 안에 같은 요청 식별자와 동일한 주문 내용을 다시 보내면 기존 주문 참조 번호를 반환합니다. 같은 식별자를 다른 내용과 함께 사용하면 호출자가 해결해야 할 충돌을 반환합니다. 식별자의 적용 범위와 보존 기간을 명시적으로 정의하세요. 이후 수정이 필요한 오류와 일시적인 장애를 구분하세요. 타임아웃만으로는 주문 저장 여부를 알 수 없으므로 호출자는 다음 행동을 정하기 전에 결과를 확인할 방법이 필요합니다.
- 배송 주소 누락: 필드 수준의 설명을 반환하고, 재전송 전에 요청을 수정합니다.
- 불확실한 결과: 요청 식별자를 조회하고 기록된 상태와 대조합니다.
- 일시적인 서비스 장애: 합의한 재시도 정책을 따르며, 시도할 때마다 새로운 주문 식별 정보를 생성하지 않습니다.
계약을 테스트하고 변경하는 방법을 합의하세요
두 팀이 정상 주문, 반복 요청, 유효하지 않은 주소, 확인 응답 중단을 차례로 검토하게 하세요. 각 상황에서 같은 결과를 기대하는지 확인하세요. 이 예시들을 명세와 함께 보관하고 통합이 바뀔 때 활용하세요. 변경 승인, 연결된 팀에 대한 공지, 장애 조사를 맡을 사람을 정하세요. 인계 자료에는 불필요한 고객 정보를 노출하지 않고 지원 담당자가 요청을 추적하는 방법과, 호환되지 않는 변경을 기존 API 사용자에게 도입하는 방법을 설명해야 합니다.