Os exemplos de API são frequentemente partilhados no momento exato em que a clareza é importante. Um programador está a explicar um formato de resposta, um engenheiro de suporte está a reproduzir uma carga útil ou um escritor de documentos está a transformar um snippet interno em documentação pública. Se o JSON for minificado, inconsistente ou inválido, a conversa ficará mais lenta imediatamente.
Formatar o JSON antes de o partilhar é um pequeno passo que facilita a inspeção da estrutura. Também oferece a oportunidade de detetar erros de análise antes que o snippet chegue a outra pessoa. O Conversor JSON/YAML/TOML do Converty suporta este fluxo de trabalho, permitindo validar, embelezar, reduzir e converter dados estruturados no browser.
Uma boa formatação torna a estrutura revisável
O JSON em bruto pode ser tecnicamente válido e ainda assim difícil de ler. As cargas longas de linha única ocultam aninhamentos, arrays e campos repetidos. O recuo inconsistente torna mais difícil ver se um valor pertence ao objeto acima dele ou a um filho aninhado.
Ao formatar JSON, torna a forma visível. Isto é importante para exemplos de API porque os revisores procuram frequentemente estrutura, e não apenas valores. Têm de ver quais os campos obrigatórios, como os arrays estão organizados e se o exemplo corresponde ao texto à sua volta.
Um fluxo de trabalho prático antes de partilhar JSON
Antes de colar um exemplo de API num documento, problema, resposta de suporte ou pull request, aplique um passo de limpeza.
1.º Abra o Conversor JSON/YAML/TOML. 2.º Cole o excerto JSON. 3.º Confirme se analisa sem erros. 4. Utilize a saída formatada para documentação ou revisão. 5. Utilize a saída reduzida apenas quando o destino necessitar especificamente de JSON compacto.
Este fluxo de trabalho não substitui o teste de uma API. É uma verificação de legibilidade e validade do exemplo que está prestes a partilhar.
A formatação e a validação estão relacionadas, mas não são idênticas
A formatação altera a forma como o JSON é apresentado. A validação verifica se o JSON pode ser analisado. Ambos são importantes antes de partilhar.
Se o snippet for inválido, a formatação não poderá corrigir a estrutura subjacente sem alterar os dados. Se o snippet for válido, mas comprimido numa linha, a validação por si só não facilitará a leitura. Um bom passe de pré-partilha faz as duas coisas: confirma que o JSON é válido e torna-o legível.
Para uma comparação mais profunda, leia Formatador JSON vs Validador JSON: O que precisa antes de colar?.
Quando a conversão ajuda na revisão
Por vezes, as pessoas que analisam os dados não querem o JSON como formato final. Uma nota de implantação pode necessitar de YAML. Uma explicação de configuração pode discutir o TOML. A conversão de formatos pode ajudar as pessoas a compreender os mesmos dados na sintaxe que o seu próximo sistema espera.
Isto não significa que cada snippet JSON se possa tornar em qualquer outro formato com segurança. Algumas estruturas não estão mapeadas de forma limpa, e é por isso que o Converty apresenta avisos de compatibilidade quando necessário. Se o TOML fizer parte da decisão, leia Porque é que a saída TOML não está disponível para algumas entradas JSON ou YAML.
Abra o Conversor JSON/YAML/TOML antes de partilhar um exemplo de API quando necessita de validar, formatar ou converter o snippet para um formato de revisão mais limpo.
