API Gateway에서 진짜 스트리밍 구현하기

최근 Amazon API Gateway(API Gateway)가 REST API에서 “응답 스트리밍(response streaming)”을 공식 지원하기 시작했다는 소식이다. 이 덕분에, text/event-stream (즉, Server-Sent Events, SSE) 같은 스트리밍‑기반 응답을 API Gateway를 통해 “프로그레시브 전달(progressive delivery)” 방식으로 구현할 수 있게 됐다.(Amazon Web Services, Inc.)

✅ 왜 이 변화가 중요해졌나

• 이전까지 API Gateway는 통상 응답을 완전히 버퍼링(buffering)한 뒤 한 번에 보내는 방식이었다. 이러면 응답이 늦어지고 특히 생성형 AI, 큰 파일 전송, 실시간 피드백 같은 use‑case에서 사용자 경험이 나빠졌다.(Amazon Web Services, Inc.)

• 새로 추가된 response streaming 기능을 사용하면, 백엔드에서 데이터가 준비되는 즉시 클라이언트로 바이트를 순차적으로 전송할 수 있다. 덕분에 “타자 치듯이 응답이 올라오는” 경험을 구현할 수 있고, 지연 시간(Time‑to‑First‑Byte, TTFB)이 크게 줄어든다.(Amazon Web Services, Inc.)

• 또한, 스트리밍을 통해 더 큰 페이로드(예: PDF, 이미지, 대용량 데이터)를 처리하거나, 최대 15분까지 걸리는 긴 작업(long‑running 작업)에 대해 점진적인 진행 상황을 클라이언트에 전달할 수 있다.(Amazon Web Services, Inc.)

⚙️ 어떻게 설정 & 사용하나

• API Gateway에서 integration 설정할 때, 기본값인 BUFFERED 대신 STREAM 으로 response transfer mode를 변경해야 한다.(AWS Documentation)

• 지원되는 integration 유형은 HTTP_PROXY, AWS_PROXY (즉, Lambda proxy 포함), 또는 Private integration 이다.(AWS Documentation)

• 스트리밍 응답을 사용할 경우, 다음 기능들은 제한된다: 응답 transformation(VTL), 통합된 응답 캐싱, 그리고 API Gateway 수준의 콘텐츠 인코딩(compression) 같은 것들.(AWS Documentation)

• 백엔드가 AWS Lambda 인 경우엔, Lambda에서도 스트리밍 가능한 함수로 작성되어야 한다. 예: Node.js 런타임에서 streamifyResponse() 같은 래퍼를 사용해 응답 스트림을 직접 쓰는 방식.(Amazon Web Services, Inc.)

💡 SSE 같은 실시간 피드용(use‑case)에서 고려할 점

• text/event-stream + SSE + 스트리밍 응답 조합은, 채팅, 실시간 로그, 진행 중 작업 피드백, 라이브 데이터 피드 등에서 Websocket API보다 간편하고 비용도 낮출 수 있는 대안이 될 수 있다. SSE는 한 방향(server → client) 통신만 필요할 때 특히 유용하다.(Wikipedia)

• 다만, 스트리밍 응답은 15분이라는 제한이 있고, idle 타임아웃이 통합 설정(Regional/private vs edge‑optimized)에 따라 다르다. 예: edge‑optimized는 30초 타임아웃.(AWS Documentation)

• 또, API Gateway 단에서 통신 최적화(중간 프록시나 압축 등)를 걸면 chunked 전송이 막히거나 지연될 수 있어, “중간 버퍼링/압축(disable intermediary buffering/compression)” 설정이 필요할 수 있다.