상태 코드 202 (Accepted) 란? API 처리 완료 알림

복잡한 보고서를 실행하기 위해 버튼을 클릭했거나, 비디오 트랜스코딩 작업을 요청했을 수도 있습니다. 페이지가 몇 분 동안 멈춰있는 대신, 즉시 "요청이 처리 승인되었습니다."라는 메시지를 받습니다. 몇 분 후, 완료된 보고서 링크가 포함된 이메일을 받게 됩니다.

이러한 부드러운 비동기 경험은 잘 설계된 현대 소프트웨어의 특징입니다. 그리고 이는 중요하지만 종종 오해되는 HTTP 상태 코드인 202 Accepted에 의해 구동됩니다.

"지금 바로 완료되었습니다"라고 말하는 사촌 격인 200 OK나 "새로운 것을 만들었습니다"라고 말하는 201 Created와 달리, 202 Accepted 상태 코드는 기대치를 관리하는 데 중점을 둡니다. 이는 서버가 "메시지를 받았습니다. 무엇을 원하는지 이해했습니다. 지금 당장 결과를 드릴 수는 없지만, 큐에 넣어 처리할 것입니다. 기다릴 필요는 없습니다."라고 말하는 방식입니다.

이는 바쁜 레스토랑 호스트에게 번호표를 건네는 것과 같습니다. 그들은 즉시 음식을 가져다주지 않지만, 당신은 대기열에서 당신의 순서가 안전하게 확보되었고 결국 식사가 준비될 것이라고 믿습니다.

오래 실행되는 작업을 처리하는 API를 구축하거나 사용하고 있다면, 202 Accepted를 이해하는 것이 반응성이 좋고 확장 가능하며 사용자 친화적인 애플리케이션을 만드는 데 핵심입니다.

그렇다면 이것이 무엇을 의미하며, 개발자, 테스터 및 API 소비자에게 왜 이것을 이해하는 것이 중요할까요?

메커니즘에 대해 자세히 알아보기 전에, 비동기 워크플로우가 필요한 API를 설계하고 있다면, 이러한 복잡한 상호작용을 테스트하고 시각화하는 데 도움이 되는 도구가 필요합니다. Apidog를 무료로 다운로드하세요. Apidog는 202 응답을 쉽게 시뮬레이션하고, 폴링 메커니즘을 테스트하며, 비동기 프로세스가 견고하고 신뢰할 수 있도록 보장하는 올인원 API 플랫폼입니다.

button

이제 202 Accepted가 무엇을 의미하는지, 언제 사용해야 하는지, 그리고 올바르게 구현하는 방법을 살펴보겠습니다.

무대 설정: 동기적 사고의 문제점

202가 왜 필요한지 이해하려면 먼저 동기적 요청의 한계를 인식해야 합니다.

일반적인 HTTP 요청-응답 주기는 동기적이며 블로킹 방식입니다:

클라이언트: 요청을 보냅니다.
클라이언트: 기다립니다... (이는 종종 "첫 바이트까지의 시간" 또는 TTFB라고 불립니다).
서버: 요청을 처리합니다 (여기에는 복잡한 계산, 데이터베이스 쿼리, 다른 서비스 호출 등이 포함될 수 있습니다).
서버: 응답을 보냅니다 (200 OK, 201 Created 등).
클라이언트: 응답을 받고 이에 따라 동작합니다.

이 모델은 사용자 프로필 가져오기, 제품 목록 검색 또는 단일 필드 업데이트와 같은 빠른 작업에 완벽하게 작동합니다. 하지만 작업이 5초, 30초, 5분씩 걸린다면 어떨까요?

연결 시간이 초과되어 오류가 발생할 수 있습니다.
사용자의 브라우저나 앱이 멈춘 것처럼 보여 끔찍한 사용자 경험을 초래할 수 있습니다.
서버 프로세스가 묶여 다른 들어오는 요청을 처리할 수 없게 되어 확장성이 저하될 수 있습니다.

202 Accepted 상태 코드는 이 문제에 대한 우아한 해결책입니다. 이는 HTTP의 블로킹 특성을 깨고 비동기 처리를 가능하게 합니다.

HTTP 202 Accepted는 실제로 무엇을 의미하는가?

HTTP 202 Accepted 상태 코드는 RFC에서 성공 응답으로 정의됩니다. 그러나 이는 매우 특정한 유형의 성공입니다. 202 Accepted 상태 코드는 일반적으로 성공을 나타내는 2xx 카테고리에 속합니다. 이는 다음을 나타냅니다:

요청이 수신되고 이해되었습니다.
요청이 처리를 위해 승인되었습니다.
처리가 아직 완료되지 않았습니다.
처리가 결과적으로 완료된 작업으로 이어질 수도 있고 그렇지 않을 수도 있습니다 (나중에 실패할 수도 있습니다).

그러나 요청이 성공적으로 처리되어 완료되었음을 의미하는 200 OK와 달리, 202는 우리에게 다른 것을 알려줍니다:

서버가 요청을 수락했지만, 처리는 아직 완료되지 않았습니다.

결정적으로, 응답은 클라이언트에게 요청의 상태를 확인할 수 있는 위치 또는 최종 결과가 미래에 제공될 위치에 대한 일부 정보를 제공해야 합니다.

다시 말해, 202는 서버가 정중하게 말하는 방식입니다:

"안녕하세요, 요청을 받았습니다. 처리 중입니다. 하지만 지금 당장 결과를 기대하지 마세요."

이것은 이메일 전송, 대규모 데이터셋 처리 또는 백그라운드 작업 시작과 같이 시간이 걸리는 비동기 작업 프로세스에 특히 유용합니다.

202 Accepted는 왜 존재하는가?

모든 요청이 즉시 처리될 수는 없습니다. API 호출을 보낼 때마다 서버가 전체 작업이 완료될 때까지 기다렸다가 응답해야 한다고 상상해 보세요. 이는 다음으로 이어질 수 있습니다:

오래 실행되는 작업에서 시간 초과.
클라이언트가 멈추기 때문에 나쁜 사용자 경험.
작업이 끝날 때까지 리소스가 묶여 있으므로 서버 과부하.

202 상태 코드는 클라이언트를 기다리게 하지 않고 서버가 요청을 승인할 수 있도록 하여 이 문제를 해결합니다.

비동기 워크플로우: 단계별 분석

구체적인 예시를 살펴보겠습니다. 개인화된 데이터 보고서를 생성하는 API를 상상해 보세요.

1단계: 클라이언트의 요청

클라이언트 애플리케이션은 보고서 생성을 시작하기 위해 POST 요청을 보냅니다.

POST /api/reports/generate HTTP/1.1Host: api.example.comContent-Type: application/jsonAuthorization: Bearer <token>
{
  "type": "annual_sales",
  "year": 2023,
  "format": "pdf"
}

2단계: 서버의 202 응답

서버는 요청을 수신합니다. 요청이 잘 구성되었고 사용자가 인증되었는지 확인합니다. 그런 다음 즉시 작업을 처리 큐(Redis, RabbitMQ 또는 Amazon SQS와 같은 시스템 사용)에 넣고 응답합니다.

HTTP/1.1 202 AcceptedLocation: <https://api.example.com/api/reports/status/job-12345Content-Type:> application/json
{
  "message": "Your report generation request has been accepted and is being processed.",
  "job_id": "job-12345",
  "status_url": "<https://api.example.com/api/reports/status/job-12345>",
  "estimated_completion_time": "2023-10-27T10:05:00Z"
}

이 응답은 엄청나게 강력합니다. 자세히 살펴보겠습니다:

HTTP/1.1 202 Accepted: 핵심 메시지: "받았습니다."
Location 헤더: 요청 상태를 모니터링할 수 있는 URL을 가리키는 표준 HTTP 헤더입니다. 이는 202 응답에 대한 모범 사례입니다.
응답 본문: 다음에 무슨 일이 일어날지에 대한 유용하고 사람과 기계가 읽을 수 있는 정보를 제공합니다. job_id와 status_url은 매우 중요합니다.

3단계: 비동기 처리

클라이언트는 이제 다른 작업을 자유롭게 수행할 수 있습니다. 한편, 서버에서는:

별도의 백그라운드 워커(또는 프로세스)가 큐에서 작업을 가져옵니다.
데이터베이스 쿼리, 데이터 컴파일, PDF 생성 등 시간이 많이 소요되는 작업을 수행합니다.
완료되면 결과를 저장(예: S3와 같은 클라우드 스토리지에)하고 작업 상태를 "완료됨"으로 업데이트합니다.

4단계: 클라이언트가 완료 여부 확인

클라이언트는 이제 202 응답에서 제공된 status_url을 폴링할 수 있습니다.

GET https://api.example.com/api/reports/status/job-12345

이 폴링 요청에 대한 응답은 시간이 지남에 따라 변경될 수 있습니다:

초기: {"status": "processing", "progress": 45}
완료 시: {"status": "completed", "download_url": "<https://api.example.com/api/reports/download/job-12345.pdf>"}

대안으로, 서버는 클라이언트가 제공한 URL로 웹훅을 통해 알림을 보낼 수 있는데, 이는 폴링보다 더 진보되고 효율적인 패턴입니다.

202 Accepted의 주요 특징

다음은 202 응답의 필수적인 특징입니다:

요청 수신됨: 서버가 귀하의 요청을 받았습니다.
처리 미완료: 실제 작업은 아직 진행 중입니다.
완료 보장 없음: 200과 달리, 202는 작업이 성공할 것이라고 약속하는 것이 아니라 단지 승인되었다는 것을 의미합니다.
비동기 워크플로우에 유용: 백그라운드 작업, 큐 또는 지연 처리.

202 Accepted vs. 다른 성공 코드: 차이점 알기

202를 다른 2xx 코드와 혼동하기 쉽습니다. 다음은 간단한 요약입니다:

200 OK: "귀하의 요청을 성공적으로 처리했으며, 지금 바로 결과가 여기 있습니다." (동기적, 즉각적인 결과)
201 Created: "새로운 리소스를 지금 바로 성공적으로 생성했습니다. 여기 해당 위치와 데이터가 있습니다." (동기적, 즉각적인 생성)
202 Accepted: "귀하의 요청을 처리할 것입니다. 나중에 다시 확인하여 결과를 확인하십시오." (비동기적, 지연된 처리)
204 No Content: "귀하의 요청을 성공적으로 처리했지만, 돌려보낼 콘텐츠가 없습니다." (동기적, 본문 없음)

결과가 즉시가 아닌 미래에 제공될 때 202를 사용하십시오.

202 Accepted를 사용하는 이유? 주요 이점

향상된 사용자 경험(UX): 클라이언트 애플리케이션은 응답성을 유지합니다. 사용자들은 죽음의 회전 바퀴 대신, 요청이 접수되었다는 즉각적인 피드백을 받습니다.
더 나은 서버 확장성: 서버의 주요 요청 처리 스레드는 거의 즉시 해제됩니다. 이들은 무거운 작업을 백그라운드 워커에게 위임하여 서버가 훨씬 더 많은 들어오는 요청을 처리할 수 있도록 합니다.
불확실성 처리: 서버는 나중에 100% 이행될 수 있을지 확신하지 못하더라도 요청을 수락할 수 있습니다. 예를 들어, 일시적으로 다운된 타사 서비스에 의존하는 요청을 수락할 수 있습니다.
복잡한 작업에 현실적: 이메일 전송, 비디오 처리, 머신러닝 모델 실행 또는 대규모 데이터 내보내기와 같이 시간이 걸리는 실제 프로세스를 정확하게 모델링합니다.

HTTP 202의 실제 사용 사례

많은 현대 애플리케이션에서 202 Accepted를 접하게 될 것입니다:

파일 처리: 이미지/비디오 트랜스코딩, 문서 변환(예: PDF 생성).
데이터 작업: 대규모 보고서 생성, 데이터 내보내기/가져오기, 대량 이메일 발송.
AI/머신러닝: 모델 학습 또는 추론을 위한 작업 제출.
결제 처리: 일부 결제 게이트웨이는 결제 요청을 비동기적으로 수락합니다.
DevOps/CI-CD: 빌드 파이프라인 트리거. API는 요청을 즉시 수락하고 빌드 로그 링크를 반환합니다.

202 Accepted 사용의 이점

개발자와 API 설계자는 왜 202를 사용해야 할까요?

클라이언트 시간 초과 방지: 사용자는 기다릴 필요가 없습니다.
확장성 향상: 서버가 긴 작업으로 인해 묶이지 않습니다.
더 나은 사용자 피드백: 침묵 대신, 클라이언트는 요청이 처리 중임을 알 수 있습니다.
비동기 아키텍처 지원: 현대 마이크로서비스에 필수적입니다.

비동기 워크플로우에서의 202 Accepted

일반적으로 다음과 같이 작동합니다:

클라이언트가 요청을 보냅니다.
서버가 202 응답과 함께 "상태 URL"을 보낼 수 있습니다.
클라이언트가 상태 엔드포인트로 다시 확인하여 작업이 완료되었는지 확인합니다.

예를 들어:

{
  "status": "processing",
  "check_status": "/jobs/12345/status"
}

이 패턴은 양쪽을 모두 만족시킵니다: 클라이언트는 즉각적인 승인을 받고, 서버는 숨 쉴 공간을 얻습니다.

Apidog로 202 워크플로우 테스트하기

비동기 API 흐름을 테스트하는 것은 간단한 동기 호출을 테스트하는 것보다 더 복잡합니다. 바로 이 지점에서 Apidog가 귀중한 도구가 됩니다.

Apidog를 사용하면 다음을 수행할 수 있습니다:

흐름 스크립트 작성: 먼저 POST 요청을 보내고 status_url과 함께 202를 반환하는지 유효성을 검사하는 테스트 시나리오를 만듭니다.
변수 추출: Apidog의 스크립팅을 사용하여 202 응답에서 job_id 또는 status_url을 자동으로 추출하고 환경 변수로 저장합니다.
폴링 테스트: 추출된 변수를 사용하여 status_url을 호출하는 후속 GET 요청을 만듭니다. Apidog를 구성하여 "완료됨" 상태를 받을 때까지 이 요청을 재시도할 수 있습니다.
최종 결과 유효성 검사: 작업이 완료되면 다운로드 URL의 최종 응답을 유효성 검사하기 위한 어설션을 작성합니다.

이를 통해 전체 비동기 여정의 테스트를 자동화하여 신뢰성을 보장하고 회귀를 방지할 수 있습니다.

202 Accepted 응답을 테스트하는 방법 (Apidog와 함께)

바로 이 지점에서 Apidog가 빛을 발합니다. 정적 도구와 달리 Apidog는 다음을 가능하게 합니다:

요청을 보내고 다양한 상태 코드(예: 202)를 시뮬레이션합니다.
비동기 워크플로우를 테스트하기 위해 API 엔드포인트를 모의(Mock)합니다.
개발자가 202 응답에서 무엇을 기대해야 하는지 알 수 있도록 API를 문서화합니다.
팀원들과 협업하여 비동기 처리를 개선합니다.

Apidog를 사용하면 도구를 전환할 필요 없이 승인부터 완료까지 종단 간 202 워크플로우를 구축하고 테스트할 수 있습니다.

button

잠재적 함정과 흔한 오해

그렇다고 해서 202가 오용될 수도 있습니다. 몇 가지 함정은 다음과 같습니다:

완료 가정: 요청이 승인되었다고 해서 성공했다는 의미는 아닙니다.
후속 조치 미제공: API는 클라이언트가 작업 상태를 확인할 수 있는 방법을 포함해야 합니다.
202 과용: 간단하고 즉각적인 작업에 사용하지 마십시오. 클라이언트를 혼란스럽게 할 것입니다.

과제 및 모범 사례

202를 올바르게 구현하려면 신중한 고려가 필요합니다.

상태 엔드포인트 제공: 이는 협상 불가능합니다. 클라이언트가 요청의 진행 상황과 최종 결과를 확인할 수 있는 URL(Location 헤더 또는 응답 본문을 통해)을 반드시 제공해야 합니다.
멱등성(Idempotency)은 중요합니다: 클라이언트가 요청이 처리되었는지 확신하지 못하는 경우(예: 네트워크 문제로 인해) 다시 시도할 수 있습니다. API는 멱등성 키를 사용하여 중복 요청을 우아하게 처리하도록 설계되어야 하며, 동일한 작업이 여러 번 큐에 추가되는 것을 방지해야 합니다.
명확한 기대치 설정: 응답 본문을 사용하여 예상 완료 시간 또는 간단한 상태 메시지(queued, processing, failed, succeeded)를 제공하십시오.
웹훅 고려: 폴링에 대한 보다 효율적인 대안으로, 클라이언트가 작업이 완료될 때 서버가 호출할 웹훅 URL을 등록하도록 허용하십시오.
실패 계획: 작업이 백그라운드에서 실패할 수 있습니다. 상태 엔드포인트는 실패를 알리고 잠재적으로 이유 코드를 제공해야 합니다.

202 Accepted 구현을 위한 모범 사례

202를 반환하는 API를 설계하고 있다면, 다음 모범 사례를 염두에 두십시오:

항상 컨텍스트 반환: 작업 ID 또는 상태 URL을 제공하십시오.
명확하게 문서화: 클라이언트가 진행 상황을 확인하는 방법을 설명하십시오.
가능하면 웹훅 사용: 작업이 완료되면 클라이언트에게 알림을 보내십시오.
과용하지 마십시오: 진정으로 비동기적인 작업에만 202를 반환하십시오.

REST vs GraphQL API에서의 202 Accepted

REST API: 요청이 종종 오래 실행되는 프로세스에 매핑되기 때문에 202가 흔합니다.
GraphQL API: GraphQL은 동기적 쿼리를 선호하므로 덜 흔하지만, 비동기 뮤테이션으로도 여전히 가능합니다.

결론: 비동기 설계 수용

HTTP 202 Accepted 상태 코드는 API 설계자의 도구 상자에 있는 강력한 도구입니다. 이는 API를 단순한 요청-응답 메커니즘으로 생각하는 것에서 벗어나 복잡한 실제 워크플로우를 조율하는 시스템으로 생각하는 전환을 나타냅니다. 202 Accepted 상태 코드가 가장 유명한 HTTP 코드는 아닐지라도, 비동기 API 워크플로우에서 중요한 역할을 합니다. 이는 클라이언트에게 "요청을 받았습니다. 하지만 아직 처리 중입니다."라고 말합니다.

202를 사용함으로써, 더 확장 가능하고, 더 탄력적이며, API를 사용하는 개발자와 궁극적으로 이점을 얻는 최종 사용자에게 훨씬 더 우수한 경험을 제공하는 API를 구축할 수 있습니다.

이는 소프트웨어의 모든 것이 즉시 발생하는 것은 아니라는 점을 인정하며, 그러한 현실을 처리하는 표준화되고 견고한 방법을 제공합니다.

따라서 다음에 오래 실행되는 작업을 위한 엔드포인트를 설계할 때, 동기적으로 만들려고 강요하지 마십시오. 작업의 비동기적 특성을 수용하십시오. 202 Accepted를 반환하고, 상태 URL을 제공하여 애플리케이션을 기다리는 요청의 억압에서 해방시키십시오. 202를 반환하는 API를 구축하거나 테스트하는 경우, 이러한 워크플로우를 번거로움 없이 시뮬레이션, 테스트 및 문서화할 수 있는 도구가 필요합니다. 이것이 바로 Apidog가 제공하는 것입니다. Apidog와 같은 도구를 사용하여 구현이 견고하고, 테스트 가능하며, 통합하기 즐겁도록 보장하십시오. API 테스트 및 문서화를 간소화할 준비가 되셨습니까? 오늘 Apidog를 무료로 다운로드하고 202 Accepted와 같은 코드 처리를 손쉽게 만드십시오.

button