멱등성(Idempotent) API 설계: 왜 중요한가와 올바른 구현 방법

멱등성(Idempotency)은 중복 결제가 발생하거나 사용자가 이중 청구를 당하기 전까지는 학술적인 개념처럼 느껴지는 주제 중 하나입니다. 멱등성 API는 동일한 요청을 여러 번 보내더라도 한 번 보냈을 때와 동일한 결과를 보장합니다. 이는 리소스를 생성, 업데이트 또는 전송하는 모든 작업에서 매우 중요합니다.

가장 간단한 구현 방법은 멱등성 키(Idempotency key)를 사용하는 것입니다. 클라이언트는 각 요청에 대해 고유한 키를 생성하여 헤더(Header)로 전송합니다. 서버는 이 키를 이전에 본 적이 있는지 확인합니다. 만약 확인되었다면, 작업을 다시 실행하지 않고 이전 응답을 반환합니다. 그렇지 않다면, 요청을 처리하고 그 결과를 멱등성 키와 함께 저장합니다.

멱등성 키는 고유 제약 조건(Unique constraint)이 있는 데이터베이스에 저장하십시오. 키에 TTL(Time To Live, 유효 기간)을 설정하십시오. 멱등성 키를 영원히 기억할 필요는 없습니다. 24시간의 창(Window)이면 대부분의 재시도(Retry) 시나리오를 커버할 수 있습니다. TTL이 만료된 후에는 동일한 키를 안전하게 재사용할 수 있습니다.

기본적으로 멱등성 작업(Idempotent operations)을 갖추도록 API를 설계하십시오. GET, PUT, DELETE는 자연스럽게 멱등합니다. POST는 명시적인 멱등성 지원이 필요합니다. PATCH는 부분 업데이트가 멱등하지 않을 수 있어 까다롭습니다. 업데이트에는 PUT을 선호하거나 버전 번호를 사용한 조건부 PATCH를 사용하십시오.

서버 측에서 재시도를 명시적으로 처리하십시오. 서버가 멱등성 키가 포함된 요청을 받았지만 아직 처리를 완료하지 않은 경우, 409 Conflict 또는 429 Too Many Requests를 반환하십시오. 클라이언트는 지수 백오프(Exponential backoff)를 사용하여 재시도해야 합니다.

멱등성을 철저하게 테스트하십시오. 네트워크 재시도, 중복 요청, 그리고 동일한 멱등성 키를 가진 동시 요청(Concurrent requests)을 시뮬레이션하십시오. 이러한 테스트는 데이터 손상으로 이어질 수 있는 미묘한 경합 조건(Race conditions)을 잡아냅니다.

멱등성은 클라이언트와 서버 사이의 계약입니다. API 명세서(API spec)에 이를 명확하게 문서화하십시오. 어떤 엔드포인트가 멱등한지, 멱등성 키를 어떻게 생성하는지, 그리고 중복 요청에 대해 어떤 응답 코드(Response codes)를 기대해야 하는지를 클라이언트에게 알려주십시오.

–

Rizwan Saleem | https://rizwansaleem.co