NDJSON 101: Streaming sobre Endpoints HTTP

No mundo orientado a dados de hoje, transferir grandes conjuntos de dados entre sistemas de maneira eficiente é crucial. Embora o JSON tenha se tornado o formato padrão para troca de dados, ele enfrenta limitações ao lidar com grandes volumes de dados ou cenários de streaming. É aqui que NDJSON (JSON Delimitado por Quebras de Linha) entra – um formato simples, mas poderoso, que está revolucionando a maneira como transmitimos dados em conexões HTTP. Neste artigo, vamos explorar o que é NDJSON, como ele difere do JSON padrão e como o Apidog pode ajudá-lo a trabalhar com endpoints de streaming NDJSON.

O que é NDJSON?

NDJSON (JSON Delimitado por Quebras de Linha) é um formato que armazena dados estruturados como uma sequência de objetos JSON, com cada objeto em sua própria linha, separado por um caractere de quebra de linha (\n). Também é conhecido como JSON Lines (JSONL) em alguns contextos.

Aqui está um exemplo simples de NDJSON:

{"id": 1, "name": "Alice", "score": 95}
{"id": 2, "name": "Bob", "score": 87}
{"id": 3, "name": "Charlie", "score": 92}

Cada linha é um objeto JSON válido e completo, facilitando o processamento de um registro por vez, sem carregar todo o conjunto de dados na memória.

NDJSON vs. JSON Tradicional: Principais Diferenças

JSON tradicional e NDJSON servem a propósitos diferentes e têm características distintas:

A principal vantagem do NDJSON é sua capacidade de ser processado de forma incremental. Com o JSON tradicional, você precisa analisar todo o arquivo antes de acessar qualquer dado. Com o NDJSON, você pode ler e processar uma linha por vez, tornando-o perfeito para:

• Arquivos de log
• Streaming de dados
• Grandes conjuntos de dados
• Processamento de dados em tempo real

Por que usar NDJSON para Streaming HTTP?

Streaming HTTP permite que servidores enviem dados para clientes de forma incremental, em vez de esperar que toda a resposta esteja pronta. O NDJSON é particularmente adequado para streaming HTTP porque:

1. Simplicidade: Cada linha é um objeto JSON completo e válido
2. Compatibilidade: Funciona com analisadores JSON existentes
3. Processamento Incremental: Os clientes podem processar dados à medida que chegam
4. Eficiência de Memória: Não é necessário armazenar em buffer toda a resposta
5. Legibilidade Humana: Fácil de inspecionar e depurar

Como transmitir NDJSON por meio de Endpoints HTTP

Implementar streaming NDJSON por meio de HTTP é simples. Veja como funciona tanto no lado do servidor quanto no lado do cliente:

Implementação do Lado do Servidor

Para criar um endpoint HTTP que transmita NDJSON:

Defina os cabeçalhos apropriados:

Content-Type: application/x-ndjson
Transfer-Encoding: chunked

Escreva cada objeto JSON no fluxo de resposta, seguido por um caractere de quebra de linha:

// Exemplo em Node.js
app.get('/api/data/stream', (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Transfer-Encoding', 'chunked');
  
  // Transmitir dados à medida que se tornam disponíveis
  dataSource.on('data', (item) => {
    res.write(JSON.stringify(item) + '\n');
  });
  
  dataSource.on('end', () => {
    res.end();
  });
});

Processamento do Lado do Cliente

No lado do cliente, você precisa:

1. Fazer uma solicitação HTTP para o endpoint de streaming
2. Processar a resposta de forma incremental, linha por linha
3. Parser cada linha como um objeto JSON

Aqui está um simples exemplo em JavaScript:

async function consumeNdjsonStream(url) {
  const response = await fetch(url);
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    
    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop(); // Manter a última linha incompleta
    
    for (const line of lines) {
      if (line.trim() === '') continue;
      const jsonObject = JSON.parse(line);
      processData(jsonObject); // Fazer algo com os dados
    }
  }
}

Casos de Uso Comuns para Streaming NDJSON

O streaming NDJSON é particularmente valioso em cenários como:

• Análise em tempo real: Transmitir dados de eventos para processamento imediato
• Agregação de logs: Enviar continuamente logs de aplicativos para sistemas de monitoramento
• Exportações de dados: Transferir grandes conjuntos de dados sem restrições de memória
• Aplicações IoT: Processar dados de sensores à medida que são gerados
• Feeds de atividades: Entregar eventos de mídia social ou de aplicativos em tempo real

Testando Endpoints NDJSON com Apidog

Apidog, a plataforma abrangente de desenvolvimento de API, oferece suporte embutido para testar e depurar endpoints de streaming NDJSON. Veja como o Apidog simplifica o trabalho com NDJSON:

1. Visualização de Stream em Tempo Real

A interface do Apidog exibe respostas NDJSON em tempo real, mostrando cada objeto JSON à medida que chega do servidor. Isso facilita a monitoração de dados de streaming sem escrever código personalizado.

2. Análise e Formatação Automática

O Apidog analisa automaticamente cada linha de NDJSON à medida que chega, formatando-a para legibilidade enquanto preserva a natureza de streaming da resposta.

3. Configuração de Solicitação

O Apidog torna simples a configuração dos cabeçalhos e parâmetros necessários para solicitações de streaming NDJSON, garantindo uma comunicação adequada com seus endpoints de streaming.

Guia Passo a Passo para Streaming de Endpoints HTTP que Retornam NDJSON

Para testar um endpoint de streaming NDJSON no Apidog:

Passo 1: Crie uma nova solicitação HTTP

Passo 2: Defina o método de solicitação

Passo 3: Insira a URL do seu endpoint de streaming

Passo 4: Envie a solicitação

Passo 5: Veja o resultado do teste

Observe enquanto o Apidog exibe a resposta de streaming NDJSON em tempo real

Você pode optar por mesclar as mensagens NDJSON retornadas em uma resposta completa. Saiba mais aqui.

Conclusão

NDJSON oferece uma solução elegante para transmitir dados estruturados por meio de HTTP, combinando a flexibilidade do JSON com a eficiência do processamento linha a linha. Seja construindo análises em tempo real, sistemas de processamento de logs ou funcionalidade de exportação de dados, o NDJSON oferece uma abordagem simples, mas poderosa, para lidar com dados de streaming.

Com o suporte do Apidog para streaming NDJSON, testar e depurar esses endpoints se torna significativamente mais fácil. Você pode visualizar, inspecionar e validar seus dados de streaming sem escrever código personalizado, acelerando seu processo de desenvolvimento e garantindo que suas APIs de streaming funcionem como esperado.

Comece a explorar o streaming NDJSON com o Apidog hoje e experimente o poder do processamento de dados em tempo real em suas aplicações!