O blog da AWS

Construindo APIs responsivas com streaming de resposta do Amazon API Gateway

Por Anton Aleksandrov, Prin. SSA, Serverless e Giedrius Praspaliauskas, Sr SSA, Serverless.

Hoje, a AWS anunciou suporte para streaming de resposta no Amazon API Gateway para melhorar significativamente a capacidade de resposta de suas APIs REST transmitindo progressivamente payloads de resposta de volta ao cliente. Com essa capacidade, você pode usar respostas transmitidas para aprimorar a experiência do usuário ao construir aplicações baseadas em LLM (como agentes de IA e chatbots), melhorar o desempenho de time-to-first-byte (TTFB) para aplicações web e móveis, transmitir arquivos grandes e realizar operações de longa duração enquanto relata progresso incremental usando protocolos como server-sent events (SSE).

Nesta publicação você aprenderá sobre essa capacidade, os desafios que ela aborda e como usar o streaming de resposta para melhorar a capacidade de resposta de suas aplicações.

Visão geral

Considere este cenário – você está executando uma aplicação agêntica baseada em IA que usa um Amazon Bedrock foundation model. Seus usuários interagem com a aplicação através de uma API, fazendo perguntas complexas que requerem respostas detalhadas. Antes do streaming de resposta, os usuários enviariam seus prompts e esperariam para eventualmente receber a resposta da aplicação, às vezes por dezenas de segundos. Essa pausa desconfortável entre perguntas e respostas criava uma experiência fragmentada e não natural.

Com a capacidade de streaming de resposta do API Gateway, a interação através da API se torna muito mais fluida e natural. Assim que sua aplicação começa a processar a resposta do modelo, você pode transmiti-la de volta aos seus usuários usando o API Gateway.

A animação a seguir ilustra essa melhoria significativa na experiência do usuário. O prompt à esquerda é processado usando uma resposta sem streaming com o usuário tendo que esperar vários segundos para receber o resultado. O prompt à direita está usando o streaming de resposta do API Gateway, reduzindo significativamente o TTFB e melhorando a experiência do usuário.

Figura 1. Comparando a experiência do usuário antes (esquerda) e depois (direita) de ativar o streaming de resposta do API Gateway ao retornar uma resposta de um foundation model do Bedrock.

Seus usuários agora podem ver respostas de IA aparecerem em tempo real, palavra por palavra, como ver alguém digitando. Esse feedback imediato faz com que suas aplicações pareçam mais responsivas e envolventes, mantendo os usuários conectados durante toda a interação. Além disso, você não precisa se preocupar com limites de tamanho de resposta ou implementar soluções alternativas complexas – o streaming acontece automaticamente e eficientemente, permitindo que você se concentre em construir ótimas experiências de usuário em vez de gerenciar restrições de infraestrutura.

Entendendo o streaming de resposta

No modelo tradicional de requisição-resposta, as respostas devem ser totalmente computadas antes de serem enviadas ao cliente. Isso pode impactar negativamente a experiência do usuário – o cliente deve esperar que a resposta completa seja gerada no lado do servidor e transmitida pela rede. Isso é especialmente evidente em aplicações em nuvem interativas e sensíveis à latência, como agentes de IA, chatbots, assistentes virtuais ou geradores de música.

Figura 2. A resposta é retornada ao cliente somente após ter sido totalmente gerada, aumentando a latência de time-to-first-byte.

Outro cenário importante é retornar payloads de resposta maiores, como imagens, documentos grandes ou conjuntos de dados. Em alguns casos, esses payloads podem exceder o limite de tamanho de resposta de 10 MB ou o limite de timeout de integração padrão de 29 segundos do API Gateway. Antes do streaming de resposta, os desenvolvedores contornavam essas limitações usando URLs pré-assinadas do Amazon S3 para baixar respostas grandes ou aceitando RPS mais baixo para um aumento no timeout. Embora funcionais, essas soluções alternativas introduziam latência adicional e complexidade arquitetural.

Com o suporte ao streaming de resposta você pode abordar esses desafios. Agora você pode atualizar suas APIs REST para retornar respostas transmitidas, aprimorando significativamente a experiência do usuário, melhorando o desempenho de TTFB, suportando tamanhos de payload de resposta que excedem 10 MB e atendendo requisições que podem levar até 15 minutos.

Figura 3. O streaming de resposta reduz o time-to-first-byte e melhora a experiência do usuário.

A capacidade de streaming de resposta já está entregando desempenho significativo para organizações:

“Trabalhar em estreita colaboração com as equipes da AWS para ativar o streaming de resposta foi fundamental para avançar nosso roteiro para entregar as experiências de vitrine mais performáticas para nossos maiores clientes no Salesforce Commerce Cloud. Nossa colaboração excedeu nossas metas de Core Web Vitals; vimos nossas métricas de Total Blocking Time caírem mais de 98%, o que permitirá que nossos clientes impulsionem maiores receitas e taxas de conversão.”, diz Drew Lau, Diretor Sênior de Gerenciamento de Produtos na Salesforce.

O streaming de resposta é suportado para qualquer integração HTTP-proxy, funções AWS Lambda (usando modo de integração proxy) e integrações privadas. Para começar, configure sua integração de API para transmitir a resposta do seu backend, conforme descrito nas seções a seguir, e reimplante sua API para que as alterações entrem em vigor.

Começando com o streaming de resposta

Para ativar o streaming de resposta para suas APIs REST, atualize sua configuração de integração para definir o modo de transferência de resposta como STREAM. Isso permite que o API Gateway comece a transmitir a resposta ao cliente assim que os bytes de resposta ficarem disponíveis. Ao usar o streaming de resposta, você pode configurar o timeout de requisição para até 15 minutos. Para a melhor experiência de usuário de time to first byte, a AWS recomenda fortemente que sua integração de backend também implemente streaming de resposta.

Você pode ativar o streaming de resposta de várias maneiras diferentes, conforme ilustrado nos seguintes trechos:

Usando o console do API Gateway, ao criar integrações de método, selecione Stream para o modo de transferência de resposta.

Figura 4. Ativando o streaming de resposta no Console do API Gateway.

Definindo o modo de transferência de resposta usando a especificação Open API:

paths:
  /products:
    get:
      x-amazon-apigateway-integration:
        httpMethod: "GET"
        uri: "https://example.com"
        type: "http_proxy"
        timeoutInMillis: 300000
        responseTransferMode: "STREAM"

Definindo o modo de transferência de resposta usando frameworks de infraestrutura como código (IaC), como AWS CloudFormation. Observe o fragmento Uri /response-streaming-invocations, ele informa ao API Gateway para usar o endpoint Lambda InvokeWithResponseStreaming:

MyProxyResourceMethod:
  Type: 'AWS::ApiGateway::Method'
  Properties:
    RestApiId: !Ref LambdaSimpleProxy
    ResourceId: !Ref ProxyResource
    HttpMethod: ANY
    Integration:
      Type: AWS_PROXY
      IntegrationHttpMethod: POST
      ResponseTransferMode: STREAM
      Uri: !Sub arn:aws:apigateway:${APIGW_REGION}:lambda:path/2021-11-
           15/functions/${FN_ARN}/response-streaming-invocations

Atualizando o modo de transferência de resposta usando a AWS CLI:

aws apigw update-integration \
   --rest-api-id a1b2c2 \
   --resource-id aaa111 \
   --http-method GET \
   --patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \
   --region us-west-2

Usando streaming de resposta com funções Lambda

Ao usar funções Lambda como endpoint de integração downstream, suas funções Lambda devem estar ativadas para streaming. O API Gateway usa a API InvokeWithResponseStreaming para invocar funções, conforme ilustrado no diagrama a seguir, e requer integração proxy do Lambda. Consulte a documentação do API Gateway para orientações adicionais.

Figura 5. Usando o streaming de resposta do API Gateway com funções Lambda para aplicações de IA interativas.

Quando você usa o streaming de resposta com funções Lambda, o API Gateway espera que o fluxo de resposta do handler contenha os seguintes componentes (em ordem):

  • Metadados de resposta JSON – Deve ser um objeto JSON válido e pode conter apenas os campos statusCode, headers, multiValueHeaders e cookies (todos opcionais). Os metadados não podem ser uma string vazia; no mínimo devem ser um objeto JSON vazio.
  • O delimitador de 8 bytes nulos – O Lambda adiciona este delimitador automaticamente quando você usa o método integrado awslambda.HttpResponseStream.from(), conforme ilustrado abaixo. Quando não usar este método, você é responsável por adicionar o delimitador você mesmo.
  • Payload de resposta – Pode estar vazio.

O trecho de código a seguir ilustra como você pode retornar uma resposta transmitida de suas funções Lambda para que seja compatível com o streaming de resposta do API Gateway:

export const handler = awslambda.streamifyResponse(
   async (event, responseStream, context) => {

      const httpResponseMetadata = {
         statusCode: 200,
         headers: {
            'Content-Type': 'text/plain',
            'X-Custom-Header': 'some-value'
         }
      };

      responseStream = awslambda.HttpResponseStream.from(
         responseStream,
         httpResponseMetadata
      );

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

Consulte a documentação do API Gateway para diretrizes de implementação adicionais.

Usando streaming de resposta com integrações HTTP Proxy

Você pode transmitir respostas HTTP de suas aplicações usadas como endpoints de integração downstream, por exemplo servidores web executando no Amazon Elastic Container Service (Amazon ECS) ou Amazon Elastic Kubernetes Service (Amazon EKS). Neste caso, você deve usar integração HTTP_PROXY e especificar o modo de transferência de resposta como STREAM (usando o console, AWS CLI ou IaC). Reimplante sua API após modificá-la.

Figura 6. Usando o streaming de resposta do API Gateway com aplicações de servidor HTTP.

Uma vez que o API Gateway recebe uma resposta de streaming de sua aplicação, ele aguardará até que a transferência do bloco de cabeçalhos HTTP esteja completa. Em seguida, enviará ao cliente um código de status de resposta HTTP e cabeçalhos, seguidos pelo conteúdo de sua aplicação conforme é recebido pelo serviço API Gateway. Ele continuará transmitindo a resposta de sua aplicação para o cliente até que o fluxo termine (até 15 minutos).

Muitos frameworks populares de desenvolvimento de API e aplicações web fornecem abstrações de streaming de resposta. O trecho de código a seguir ilustra como você pode implementar streaming de resposta HTTP usando FastAPI:

app = FastAPI()

async def stream_response():
   yield b"Hello "
   await asyncio.sleep(1)
   yield b"World "
   await asyncio.sleep(1)
   yield b"!"

@app.get("/")
async def main():
   return StreamingResponse(stream_response(), media_type="text/plain")

Adicionando streaming de resposta em tempo real aos seus clientes HTTP

Diferentes clientes HTTP têm diferentes maneiras de processar fragmentos de resposta transmitidos conforme chegam. O trecho de código a seguir ilustra como processar uma resposta transmitida com uma aplicação Node.js:

const request = http.request(options, (response)=>{
   response.on('data', (chunk) => {
      console.log(chunk);
   });

   response.on('end', () => {
      console.log('Response complete');
   });
});

request.end();

Ao usar CURL, você pode usar o argumento –no-buffer para imprimir fragmentos de resposta conforme chegam.

curl --no-buffer {URL}

Código de exemplo

Clone este projeto de exemplo do GitHub para ver o streaming de resposta do API Gateway em ação. Siga as instruções no README.md para provisionar o projeto de exemplo em sua conta AWS.

Considerações

Antes de ativar o streaming de resposta, considere:

  • O streaming de resposta está disponível para APIs REST e pode ser usado com integrações HTTP_PROXY, integrações Lambda (em modo proxy) e integrações privadas.
  • Você pode usar o streaming de resposta do API Gateway com qualquer tipo de endpoint, como Regional, Privado e Otimizado para borda, com ou sem nomes de domínio personalizados.
  • Ao usar o streaming de resposta, você pode configurar timeouts de resposta de até 15 minutos, de acordo com os requisitos do seu cenário.
  • Todas as respostas de streaming de endpoints Regionais ou Privados estão sujeitas a um timeout de inatividade de 5 minutos. Todas as respostas de streaming de endpoints otimizados para borda estão sujeitas a um timeout de inatividade de 30 segundos.
  • Dentro de cada resposta de streaming, os primeiros 10MB de payload de resposta não estão sujeitos a nenhuma restrição de largura de banda. Dados de payload de resposta que excedem 10MB são restritos a 2MB/s.
  • O streaming de resposta é compatível com capacidades de segurança do API Gateway, como autorizadores, WAF, controles de acesso, TLS/mTLS, limitação de requisições e registro de acesso.
  • Ao processar respostas transmitidas, os seguintes recursos não são suportados: transformação de resposta com VTL, cache de resposta de integração e codificação de conteúdo.
  • Sempre proteja suas APIs contra acesso não autorizado e outras ameaças de segurança potenciais implementando autorização adequada com Lambda Authorizers ou Amazon Cognito User Pools. Leia a documentação de proteção de API REST e a documentação de segurança do API Gateway para detalhes adicionais.

Observabilidade

Você pode continuar usando as capacidades de observabilidade existentes, como logs de execução, logs de acesso, integração com AWS X-Ray e métricas do Amazon CloudWatch com o streaming de resposta do API Gateway.

Além das variáveis de logs de acesso existentes, as seguintes novas variáveis estão disponíveis:

  • $content.integration.responseTransferMode – o modo de transferência de resposta de sua integração. Pode ser BUFFERED ou STREAMED.
  • $context.integration.timeToAllHeaders – o tempo entre quando o API Gateway estabelece a conexão de integração até quando recebe todos os cabeçalhos de resposta de integração do cliente.
  • $context.integration.timeToFirstContent – o tempo entre quando o API Gateway estabelece a conexão de integração até quando recebe os primeiros bytes de conteúdo.

Consulte a documentação do API Gateway para mais informações.

Preços

Com essa capacidade, você continua pagando as mesmas taxas de invocação de API para respostas transmitidas. Cada 10MB de dados de resposta, arredondados para os 10MB mais próximos, é cobrado como uma única requisição. Consulte a página de preços do API Gateway para detalhes adicionais.

Conclusão

A capacidade de streaming de resposta para o Amazon API Gateway aprimora como você pode construir e entregar APIs responsivas na nuvem. Com transmissão imediata de dados de resposta assim que ficam disponíveis, você pode melhorar significativamente o desempenho de time-to-first-byte e superar limitações tradicionais de tamanho de payload e timeout. Isso é particularmente valioso para aplicações baseadas em IA, transferências de arquivos e experiências web interativas que exigem capacidade de resposta em tempo real.

Para saber mais sobre o streaming de resposta do API Gateway, consulte a documentação do serviço.

Para saber mais sobre a construção de arquiteturas Serverless, consulte o Serverless Land.

Este conteúdo foi traduzido do post original do blog, que pode ser encontrado aqui.

Autores

Anton Aleksandrov, Prin. SSA, Serverless
Giedrius Praspaliauskas, Sr SSA, Serverless

Tradutores

Rodrigo Peres é Arquiteto de Soluções na AWS, com mais de 20 anos de experiência trabalhando com arquitetura de soluções, desenvolvimento de sistemas e modernização de sistemas legados.

Daniel Abib é arquiteto de soluções sênior na AWS, com mais de 25 anos trabalhando com gerenciamento de projetos, arquiteturas de soluções escaláveis, desenvolvimento de sistemas e CI/CD, microsserviços, arquitetura Serverless & Containers e segurança. Ele trabalha apoiando clientes corporativos, ajudando-os em sua jornada para a nuvem.

https://www.linkedin.com/in/danielabib/