Formatar Resposta de API JSON

Resposta Formatada

Aplicar um formatador à entrada minificada produz:

{
  "status": "success",
  "data": {
    "users": [
      {
        "id": 1,
        "name": "Alice Chen",
        "email": "alice@example.com",
        "role": "admin",
        "created_at": "2024-01-15T08:30:00Z"
      },
      {
        "id": 2,
        "name": "Bob Martinez",
        "email": "bob@example.com",
        "role": "editor",
        "created_at": "2024-03-22T14:15:00Z"
      },
      {
        "id": 3,
        "name": "Carol Williams",
        "email": "carol@example.com",
        "role": "viewer",
        "created_at": "2024-06-10T11:45:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "per_page": 25
  },
  "meta": {
    "request_id": "req_abc123",
    "response_time_ms": 42
  }
}

A estrutura é imediatamente legível: um envelope de sucessó contendo uma lista paginada de usuários mais metadados da requisição.

Por Que o JSON Formatado Importa para Depuração

Quando você usa curl para consultar uma API e recebe um muro de JSON minificado, a primeira coisa que faz é passá-lo por um formatador. A razão é prática: estruturas aninhadas são invisíveis em uma única linha. Sem indentação, você não pode escanear uma chave faltante, notar um valor null ou verificar o comprimento de um array.

O JSON formatado torna várias tarefas de depuração muito mais rápidas:

• Encontrar campos null ou faltantes inesperados. Quando cada chave está em sua própria linha, um campo faltante salta imediatamente em vez de estar oculto dentro de uma string longa.
• Verificar o aninhamento. Na forma minificada, o JSON profundamente aninhado requer contar chaves e parênteses manualmente. A indentação torna a estrutura de árvore visível instantaneamente.
• Fazer diff de respostas. Dois blobs JSON minificados diff como uma única linha alterada mesmo se apenas um campo mudou. JSON formatado diff limpa, mostrando exatamente qual campo mudou.
• Ler em code review. Fixtures de teste JSON no controle de versão devem sempre ser formatadas para que diffs sejam revisáveis.

Estruturas Comuns de Resposta de API REST

O exemplo acima segue um padrão amplamente usado: um campo status no nível superior, um objeto data contendo o payload real é um objeto meta com informações de nível de requisição. Variações deste padrão aparecem constantemente:

Envelope JSend

{
  "status": "success",
  "data": { ... }
}

Envelope JSON:API

{
  "data": [ ... ],
  "links": { "next": "...", "self": "..." },
  "meta": { "total": 42 }
}

Resposta de erro

{
  "status": "error",
  "code": "RESOURCE_NOT_FOUND",
  "mensagem": "User 99 does not exist",
  "request_id": "req_xyz789"
}

Formatar qualquer um destes torna a estrutura do envelope imediatamente óbvia, o que ajuda quando você está escrevendo um cliente e precisa entender qual caminho percorrer para alcançar os dados desejados.

Convenções de Indentação

As duas escolhas dominantes são 2 espaços e 4 espaços. Tabulações também são espaço em branco JSON válido mas menos comuns em configuração compartilhada.

2 espaços é o padrão em muitas ferramentas JavaScript. JSON.stringify(obj, null, 2) e jq ambos produzem saída de 2 espaços. Mantém estruturas aninhadas compactas, o que importa se você trabalha rotineiramente com JSON profundamente aninhado.

4 espaços é a convenção Python. json.dumps(obj, indent=4) é o snippet Python mais comum que você encontrará. Também é o padrão em muitos formatadores de IDE.

Escolha com base no que sua equipe já usa. Se você tem um .editorconfig ou uma configuração Prettier de nível de projeto, ela já específica o tamanho da indentação. Use isso. Não misture larguras de indentação no mesmo arquivo ou no mesmo repositório.

Formatando JSON na Linha de Comando

jq é a ferramenta padrão para formatação e consulta de JSON na linha de comando. Instale uma vez (brew install jq ou apt install jq) e você a usará constantemente.

Formatar uma string bruta:

echo '{"name":"Alice","role":"admin"}' | jq .

Formatar um arquivo:

jq . response.json

Formatar uma resposta curl inline:

curl -s https://api.example.com/users | jq .

Extrair um valor aninhado enquanto formata a resposta:

curl -s https://api.example.com/users | jq '.data.users[0].email'

Se jq não estiver disponível, a biblioteca padrão do Python cobre o casó básico:

echo '{"name":"Alice"}' | python3 -m json.tool

Ou, usando Node.js:

node -e "let d=''; process.stdin.on('data', c => d+=c); process.stdin.on('end', () => console.log(JSON.stringify(JSON.parse(d), null, 2)))" < file.json

Validando JSON Enquanto Formata

Um formatador que analisa JSON antes de re-emiti-lo também válida a entrada. Se seu JSON tem um erro de sintaxe (uma vírgula final, uma chave sem aspas, um parêntese faltante), o formatador o pegará e mostrará onde a análise falhou. Isso é um ciclo de feedback mais rápido que implantar código e esperar por um erro de análise JSON em tempo de execução.

Erros comuns de sintaxe JSON:

• Vírgulas finais após a última chave em um objeto ou último elemento em um array. Válido em literais de objeto JavaScript mas não em JSON.
• Strings com aspas simples. JSON exige aspas duplas em todos os lugares.
• Chaves sem aspas. {name: "Alice"} é JavaScript, não JSON.
• Comentários. JSON não tem sintaxe de comentários. // ou /* */ causarão falha de análise.

Se você precisa de um formato similar a JSON com comentários e vírgulas finais, veja JSON5 ou JSONC, mas esteja ciente que analisadores JSON padrão os rejeitarão.