Payload, cabeçalhos e formatos

Dois sistemas podem trocar os mesmos dados em JSON, em XML ou em campos de formulário. Para interpretar a mensagem, o serviço que recebe precisa reconhecer o formato declarado e encontrar, no corpo, dados escritos de fato nesse formato. Quando os dois não combinam, a recusa pode parecer um erro de negócio.

Corpo e cabeçalhos

O corpo de uma mensagem HTTP leva os dados da operação, quando a operação tem dados. Payload é o conteúdo transportado, e no dia a dia das APIs a palavra costuma designar o corpo enviado ou recebido. Uma consulta por GET, em geral, não tem corpo, e os dados da consulta vão na URL.

Os cabeçalhos levam as informações de controle: o formato, a credencial, o rastreio, o tamanho e as preferências de resposta. Os campos de negócio, como o valor de uma cobrança, ficam no corpo. Um cabeçalho e um campo do corpo podem ter nomes parecidos e funções diferentes.

Content-Type e Accept

Três cabeçalhos tratam do conteúdo da troca:

• Content-Type: o tipo do conteúdo enviado naquela mensagem, como application/json. O cliente informa esse cabeçalho na requisição, e o serviço informa o mesmo cabeçalho na resposta.
• Accept: os tipos de resposta que o cliente aceita receber.
• Content-Length: o tamanho do corpo, em bytes.

Quando o serviço não aceita o tipo declarado no Content-Type, a resposta prevista pelo HTTP é o código 415, de tipo de mídia não suportado. Quando o serviço não consegue responder em nenhum dos tipos pedidos no Accept, a resposta prevista é o código 406, de conteúdo não aceitável. Uma requisição que declara JSON, mas envia um corpo que não é um JSON válido, costuma receber o código 400, de requisição inválida. Cada API classifica as validações à sua maneira, e a descrição do erro, no corpo da resposta, completa a informação do código.

Os formatos mais comuns

• application/json: o JSON, usado pela maioria das APIs REST e pelas chamadas GraphQL sobre HTTP;
• application/xml e text/xml: o XML, usado em integrações mais antigas e em serviços fiscais;
• application/soap+xml: o SOAP na versão 1.2, enquanto o SOAP 1.1 usa o tipo text/xml e o cabeçalho SOAPAction;
• application/x-www-form-urlencoded: campos de formulário codificados, no formato campo=valor&outro=valor, comuns na obtenção de tokens;
• multipart/form-data: um corpo dividido em partes, usado no envio de arquivos junto com campos.

Um formato pode carregar outro. Em uma chamada GraphQL, o corpo é um JSON com o campo query, e o valor desse campo é um texto escrito na linguagem do GraphQL. Em uma chamada SOAP, o corpo é um XML com um envelope, e a mensagem da operação vai dentro desse envelope.

Formato e codificação de caracteres

A codificação de caracteres define como as letras e os símbolos viram bytes. O JSON trocado entre sistemas usa o UTF-8. Arquivos, bancos e sistemas mais antigos podem usar outras codificações, como a ISO-8859-1 ou a Windows-1252, e o Content-Type pode declarar a codificação com o parâmetro charset, como em text/xml; charset=UTF-8.

O nome João, gravado em UTF-8 e lido como Windows-1252, aparece como João. Esse tipo de troca sugere que os bytes foram interpretados com uma codificação diferente da usada na gravação, ou que uma conversão anterior saiu errada. A troca pode ter acontecido no envio, no recebimento ou só na ferramenta que exibe o log. A comparação da mensagem preservada com a codificação esperada vem antes de qualquer alteração nos dados.