[AWS] API Gateway REST API Response Streaming 구성 가이드

API Gateway가 REST API에 대해 Response Streaming(응답 스트리밍) 기능을 공식 지원하기 시작했습니다. 이 기능은 백엔드에서 생성되는 데이터가 완전히 준비될 때까지 기다리지 않고, 데이터가 생성되는 즉시 클라이언트에 전달할 수 있도록 만들어줍니다.

결과적으로 다음과 같은 이점을 가집니다:

• 사용자 경험 개선: 첫 바이트 도달 시간(Time-To-First-Byte, TTFB) 단축
• 대용량 응답 처리: 10 MB 이상의 페이로드도 스트리밍 가능
• 장시간 처리 지원: 타임아웃을 최대 15분까지 확장 가능
• 생성형 AI, 미디어 스트리밍, 대용량 데이터 다운로드 등 다양한 사용 사례에 유용

기존에는 Lambda 응답 버퍼링, S3 presigned URL 우회, WebSocket 또는 별도 스트리밍 서버 등 우회 방식을 써야 했지만, 이제 REST API만으로도 쉽게 구현할 수 있습니다.

 

API Gateway REST API Response Streaming

---

Response Streaming이 작동하는 방식

• 기본적으로 API Gateway는 통합 응답(integration response)을 모두 수신한 후 클라이언트로 전달합니다. (BUFFERED 모드)
• Response Streaming을 사용하면, 응답 전송 방식을 STREAM으로 설정하여 백엔드에서 첫 바이트가 준비되는 즉시 클라이언트로 전달이 시작됩니다.
• 스트리밍은 REST API의 모든 엔드포인트 유형 Regional, Edge-optimized, Private 에서 지원됩니다.
• 스트리밍 가능한 통합은 다음과 같습니다.
  • AWS Lambda (proxy integration, streaming-enabled)
  • HTTP proxy integration (예: ECS / EKS / 외부 HTTP 서버)
  • Private integration + proxy
• 스트리밍 모드에서 주의할 점:
  • 기본 제한이었던 10 MB 응답 크기 제한이 사라지지만, 전체 스트리밍 속도 및 idle timeout 제한이 존재합니다.
  • responseTransferMode 기본값은 BUFFERED이므로, 반드시 STREAM으로 설정해야 작동합니다.
  • 일부 기능(예: 응답 캐싱, VTL 변환, Content-Encoding 변환)은 스트리밍 모드와 호환되지 않습니다.

실제 설정 절차

아래는 REST API에서 Response Streaming을 활성화하는 기본 흐름입니다.

1. 통합 유형 확인 및 선택

• 백엔드가 HTTP 서버(ECS/EKS 등)라면 HTTP_PROXY integration 사용
• AWS Lambda를 사용한다면 AWS_PROXY + streaming-enabled Lambda (InvokeWithResponseStream) 사용

2. REST API 메서드 설정 변경

AWS Console 기준

1. API Gateway → 대상 REST API 선택
2. 리소스(Resource) 및 메서드(Method) 선택
3. Integration Request 설정 탭으로 이동
4. Response transfer mode를 STREAM으로 변경
5. 저장 후 API 재배포(Deploy)

IaC / OpenAPI / CloudFormation 예시 (YAML):

paths:
  /stream:
    get:
      x-amazon-apigateway-integration:
        httpMethod: GET
        type: http_proxy  # or AWS_PROXY for Lambda
        uri: https://your-backend/stream-endpoint
        responseTransferMode: "STREAM"
        timeoutInMillis: 900000  # 최대 15분

 

CloudFormation:

MyStreamingMethod:
  Type: 'AWS::ApiGateway::Method'
  Properties:
    HttpMethod: GET
    ResourceId: !Ref StreamResource
    RestApiId: !Ref MyApi
    Integration:
      Type: HTTP_PROXY
      IntegrationHttpMethod: GET
      Uri: https://your-backend/stream
      ResponseTransferMode: STREAM
      TimeoutInMillis: 900000

 

CLI로 변경하는 경우:

aws apigateway update-integration \
  --rest-api-id <api-id> \
  --resource-id <resource-id> \
  --http-method GET \
  --patch-operations op='replace',path='/responseTransferMode',value='STREAM'

 

 

설정 후 API를 redeploy 해야 변경이 반영됩니다.

백엔드 구현: Lambda 또는 HTTP 서버

Lambda (Node.js 예시)

스트리밍을 지원하려면 Lambda가 InvokeWithResponseStream 방식으로 호출되어야 하며, 응답은 metadata + 8 널 바이트 delimiter + payload 형태로 전달해야 합니다.

import { streamifyResponse, HttpResponseStream } from 'aws-lambda-stream-response';

export const handler = streamifyResponse(async (event, responseStream) => {
  const meta = { statusCode: 200, headers: { 'Content-Type': 'text/plain' } };
  responseStream = HttpResponseStream.from(responseStream, meta);

  responseStream.write('Hello');
  await new Promise(r => setTimeout(r, 500));
  responseStream.write(', ');
  await new Promise(r => setTimeout(r, 500));
  responseStream.write('world!');
  responseStream.end();
});

 

이처럼 백엔드에서 스트리밍을 제공하면, API Gateway가 받은 데이터를 즉시 클라이언트로 전달합니다.

HTTP 서버 (예: Express, FastAPI 등)

HTTP_PROXY integration을 사용하고, 서버 쪽에서도 chunked 응답 또는 streaming 응답을 제공하도록 구성하면 됩니다. API Gateway 설정만 STREAM으로 맞추면 됩니다.

주의사항 및 제한점

항목	설명
지원되는 통합	HTTP_PROXY, AWS_PROXY(Lambda), Private 통합만 지원
URL 제한 / 파일 크기	10 MB 이상 가능, 대형 payload 스트리밍 가능
타임아웃	최대 15분 (기본 REST API 타임아웃보다 연장)
비지원 기능	응답 캐싱, Content-Encoding 변환, VTL 기반 변환 등은 호환되지 않음
로그/모니터링	$context.integration.responseTransferMode, $context.integration.timeToFirstContent 등 로그 변수로 스트리밍 동작 확인 가능

스트리밍 모드를 사용하면 일부 기존 기능이 제한될 수 있으므로, 운영 환경으로 적용 전 충분한 테스트를 권장합니다.

어디에 유용한가

• 생성형 AI, LLM 기반 챗봇: 답변이 생성되는 즉시 사용자에게 전달 → 체감 성능 향상
• 대용량 파일 다운로드: 이미지·영상·데이터셋 등 S3 presigned URL 없이 바로 스트리밍 전달
• 장시간 처리 요청: 데이터 분석, 변환, 대용량 처리 등 29초 제한을 넘는 작업 지원 가능
• 실시간 피드백이 필요한 작업: 서버 센트 이벤트(SSE) 등 실시간 데이터 전달 구조에 적합

구성 흐름 요약

1. REST API의 메서드 통합 유형이 HTTP_PROXY 또는 AWS_PROXY(Lambda)인지 확인
2. Integration 설정에서 responseTransferMode를 STREAM으로 변경
3. 백엔드(Lambda 또는 HTTP 서버)를 streaming 응답 가능하도록 준비
4. API 재배포(Deploy)
5. 실제 요청을 보내어 streaming 동작, 응답 헤더 및 바이트 전송 확인
6. 필요 시 CloudWatch 액세스 로그 / X-Ray + CloudWatch 지표로 모니터링

마무리

이번 API Gateway의 Response Streaming 기능은, 기존 REST API의 구조를 유지하면서도 실시간 응답, 대용량 데이터 전송, 긴 처리 시간 등의 제약을 한꺼번에 해소해 주는 유용한 기능입니다. 특히 생성형 AI, 대용량 미디어, 실시간 피드백이 필요한 서비스라면 도입 가치가 높습니다.

 

다만 스트리밍 특성상 응답 캐싱, 변환, 일부 API Gateway 기능과의 충돌 가능성이 있으므로, 테스트 → 로그/모니터링 → 점진적 배포 순으로 신중히 진행하는 것을 추천드립니다.