TL;DR
Use Server-Sent Events (SSE) para transmitir respostas de API via HTTP. Envie Content-Type: text/event-stream e escreva eventos como data: {json}\n\n. SSE funciona para transmissão de respostas de IA, atualizações de progresso e feeds ao vivo. A Modern PetstoreAPI usa SSE para recomendações de pets com IA e atualizações de status de pedidos.
Introdução
Sua API gera recomendações de pets com IA. A resposta leva 10 segundos. Você faz os usuários esperarem ou transmite os resultados à medida que são gerados?
Com Server-Sent Events (SSE), você transmite respostas em tempo real. Os usuários veem os resultados imediatamente à medida que a IA os gera, criando uma experiência melhor.
Modern PetstoreAPI usa SSE para recomendações de pets com IA, atualizações de status de pedidos e mudanças no inventário.
Se você está testando APIs de streaming, Apidog oferece suporte a testes e validação de SSE.
Fundamentos do SSE
SSE é uma transmissão unidirecional baseada em HTTP, do servidor para o cliente.
Formato SSE
Content-Type: text/event-stream
Cache-Control: no-cache
data: {"message":"First chunk"}\n\n
data: {"message":"Second chunk"}\n\n
data: {"message":"Third chunk"}\n\n
Cada evento:
- Começa com
data: - Contém o payload
- Termina com
\n\n(duas novas linhas)
Eventos Nomeados
event: recommendation
data: {"petId":"019b4132","score":0.95}
event: recommendation
data: {"petId":"019b4127","score":0.89}
event: complete
data: {"total":2}
IDs de Evento
id: 1
data: {"message":"First"}
id: 2
data: {"message":"Second"}
O cliente pode retomar a partir do último ID se desconectado.
Implementando o Servidor SSE
Exemplo Node.js/Express
app.get('/v1/pets/recommendations/stream', async (req, res) => {
// Set SSE headers
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
// Send recommendations as they're generated
const recommendations = await generateRecommendations(req.query.userId);
for (const rec of recommendations) {
res.write(`data: ${JSON.stringify(rec)}\n\n`);
await sleep(100); // Simulate streaming delay
}
// Send completion event
res.write(`event: complete\ndata: {"total":${recommendations.length}}\n\n`);
res.end();
});
Exemplo Python/FastAPI
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import json
import asyncio
app = FastAPI()
@app.get("/v1/pets/recommendations/stream")
async def stream_recommendations(user_id: str):
async def generate():
recommendations = await get_recommendations(user_id)
for rec in recommendations:
yield f"data: {json.dumps(rec)}\n\n"
await asyncio.sleep(0.1)
yield f"event: complete\ndata: {json.dumps({'total': len(recommendations)})}\n\n"
return StreamingResponse(
generate(),
media_type="text/event-stream",
headers={
"Cache-Control": "no-cache",
"Connection": "keep-alive"
}
)
Implementação do Cliente SSE
JavaScript/Navegador
const eventSource = new EventSource(
'https://petstoreapi.com/v1/pets/recommendations/stream?userId=user-456'
);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
displayRecommendation(data);
};
eventSource.addEventListener('complete', (event) => {
const data = JSON.parse(event.data);
console.log(`Received ${data.total} recommendations`);
eventSource.close();
});
eventSource.onerror = (error) => {
console.error('SSE error:', error);
eventSource.close();
};
React Hook
import { useEffect, useState } from 'react';
function useSSE(url) {
const [data, setData] = useState([]);
const [complete, setComplete] = useState(false);
useEffect(() => {
const eventSource = new EventSource(url);
eventSource.onmessage = (event) => {
const item = JSON.parse(event.data);
setData(prev => [...prev, item]);
};
eventSource.addEventListener('complete', () => {
setComplete(true);
eventSource.close();
});
return () => eventSource.close();
}, [url]);
return { data, complete };
}
// Uso
function Recommendations({ userId }) {
const { data, complete } = useSSE(
`https://petstoreapi.com/v1/pets/recommendations/stream?userId=${userId}`
);
return (
<div>
{data.map(rec => (
<PetCard key={rec.petId} pet={rec} />
))}
{!complete && <Spinner />}
</div>
);
}
Como a Modern PetstoreAPI Usa SSE
Recomendações de Pets com IA
Transmita recomendações geradas por IA:
GET /v1/pets/recommendations/stream?userId=user-456
Accept: text/event-stream
event: recommendation
data: {"petId":"019b4132","name":"Fluffy","score":0.95,"reason":"Matches your preference for cats"}
event: recommendation
data: {"petId":"019b4127","name":"Buddy","score":0.89,"reason":"Similar to pets you liked"}
event: complete
data: {"total":2,"processingTime":850}
Atualizações de Status de Pedido
Transmita os passos do processamento do pedido:
GET /v1/orders/019b4132/status/stream
Accept: text/event-stream
data: {"status":"payment_processing","timestamp":"2026-03-13T10:30:00Z"}
data: {"status":"payment_confirmed","timestamp":"2026-03-13T10:30:02Z"}
data: {"status":"preparing_shipment","timestamp":"2026-03-13T10:30:05Z"}
event: complete
data: {"status":"shipped","trackingNumber":"1Z999AA10123456784"}
Mudanças no Inventário
Transmita atualizações de inventário em tempo real:
GET /v1/inventory/stream
Accept: text/event-stream
event: stock-change
data: {"petId":"019b4132","oldStock":5,"newStock":4}
event: price-change
data: {"petId":"019b4127","oldPrice":299.99,"newPrice":279.99}
Consulte a documentação SSE da Modern PetstoreAPI.
Testando SSE com Apidog
Apidog suporta testes de SSE:
- Crie uma requisição SSE
- Defina
Accept: text/event-stream - Conecte-se e visualize eventos em tempo real
- Valide o formato do evento
- Teste a reconexão
Melhores Práticas
1. Defina os Cabeçalhos Adequados
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
res.setHeader('X-Accel-Buffering', 'no'); // Desabilita o buffer do nginx
2. Envie Sinais de Vida
Mantenha a conexão ativa:
const heartbeat = setInterval(() => {
res.write(': heartbeat\n\n');
}, 15000);
res.on('close', () => clearInterval(heartbeat));
3. Lide com Erros de Forma Elegante
eventSource.onerror = (error) => {
if (eventSource.readyState === EventSource.CLOSED) {
// Conexão fechada, irá reconectar automaticamente
} else {
// Outro erro
console.error('SSE error:', error);
}
};
4. Use IDs de Evento para Retomar
let lastEventId = 0;
app.get('/stream', (req, res) => {
const startId = parseInt(req.headers['last-event-id'] || '0');
for (let i = startId + 1; i <= 100; i++) {
res.write(`id: ${i}\ndata: {"message":"Event ${i}"}\n\n`);
}
});
5. Feche Conexões
// Cliente
eventSource.addEventListener('complete', () => {
eventSource.close();
});
// Servidor
res.on('close', () => {
// Libere recursos
});
Conclusão
SSE é perfeito para transmitir respostas de API. É mais simples que WebSocket para comunicação unidirecional, funciona via HTTP e lida com a reconexão automaticamente.
Modern PetstoreAPI usa SSE para streaming de IA, atualizações de pedidos e feeds ao vivo. Teste endpoints SSE com Apidog.
Perguntas Frequentes
O SSE pode funcionar através de firewalls corporativos?
Sim, o SSE usa HTTP/HTTPS padrão, então funciona através da maioria dos firewalls e proxies.
Por quanto tempo as conexões SSE podem permanecer abertas?
Indefinidamente, mas use sinais de vida a cada 15-30 segundos para manter as conexões ativas através de proxies.
Posso enviar dados binários via SSE?
Não, SSE é apenas texto. Codifique dados binários em Base64 ou use WebSocket.
O SSE suporta comunicação bidirecional?
Não, SSE é apenas do servidor para o cliente. Os clientes usam requisições HTTP regulares para comunicação do cliente para o servidor.
Quantas conexões SSE um navegador pode ter?
Os navegadores limitam as conexões SSE por domínio (tipicamente 6). Use multiplexação ou WebSocket para muitas conexões.