CS Fundamentals Trainer · Guias

Protocolos: HTTP, SOAP, REST, gRPC, GraphQL, WebSockets e mensageria

Os protocolos que uma pessoa que trabalha de verdade encontra, comparados com as mesmas seis perguntas: HTTP e REST, SOAP e a família WS-*, JSON-RPC e gRPC com protobuf na rede, GraphQL, WebSockets, server-sent events e long polling, webhooks, AMQP, MQTT e STOMP, e SMTP, FTP, SFTP e SSH, com bytes de verdade, uma tabela de vocabulário de erros entre protocolos, portas, versionamento, rastreamento e um fluxo de decisão.

73 min de leitura

"Qual protocolo isto deveria usar?" costuma ser respondido por hábito: HTTP e JSON, porque foi o que o último serviço usou. Hábito não é um padrão ruim, mas ele esconde a pergunta. Um protocolo decide como dois programas se encontram, como uma mensagem é delimitada, quem pode falar primeiro, o que conta como erro e o que acontece quando um lado é atualizado e o outro não. São essas decisões que tornam um protocolo barato ou caro de conviver, muito depois de a primeira versão ir ao ar.

Este guia cobre os protocolos que uma pessoa que trabalha de verdade encontra: o HTTP como substrato, REST e SOAP por cima dele, JSON-RPC e gRPC, GraphQL, WebSockets e server-sent events, webhooks, os protocolos de mensageria (AMQP, MQTT, STOMP) e os mais antigos que se recusam a morrer (SMTP, FTP, SFTP, SSH). Ele os compara com as mesmas seis perguntas do começo ao fim, e mostra os bytes de verdade onde os bytes são o argumento.

Como ler.

Você querLeia
Uma decisão, hojeA seção 1, depois a seção 13 (escolher), depois a família que você escolheu
Entender um protocoloA seção dele; cada uma termina dizendo onde ele serve e onde não
Ler um protocolo que você nunca viuAs seis perguntas da seção 1, depois a seção 12 (as preocupações transversais)
O quadro completoEm ordem. As seções 4 (SOAP), 5 (gRPC) e 10 (mensageria) são os aprofundamentos

Que tipo de evidência há neste guia.

TipoOndeQuanto confiar
Texto de especificaçãoas RFCs e os documentos do W3C e da OASIS citados em cada seção e em Fontestanto quanto o documento; confira sempre qual versão do protocolo você tem
Bytes produzidos aquios hex dumps e os tamanhos das seções 2, 5, 6, 8 e 10foram produzidos pelo script do apêndice, em Python 3.13 e curl 8.5, e você pode executá-lo
Aritméticaas comparações de tamanho de mensagem e de idas e voltasdecorre dos tamanhos em bytes mostrados; nada é extrapolado para o seu tráfego
Medido em produçãonenhumnenhum número de latência ou de vazão aqui descreve um sistema real. A seção 12 diz o que medir no lugar

Transporte e infraestrutura têm os seus próprios guias, e este não os repete: TCP na prática, DNS, HTTP/2, HTTP/3 e CDNs, TLS e HTTPS, balanceamento de carga e o que acontece quando você digita uma URL.

1. Seis perguntas que todo protocolo responde

Em resumo. Todo protocolo desta página responde às mesmas seis perguntas. Aprenda as perguntas e um protocolo que você nunca viu fica legível em uma tarde.

#PerguntaPor que ela decide como é conviver com ele
1Delimitação: onde uma mensagem termina?Um prefixo de comprimento, um terminador ou "até a conexão fechar". Isso decide se streaming é possível e se um interpretador pode ser atacado com um comprimento que não corresponde
2Endereçamento: como uma coisa é nomeada?Um caminho de URL, um nome de método, um tópico, uma fila, uma caixa postal. Decide sobre o que um cache, um proxy ou uma regra de acesso consegue raciocinar
3Quem fala primeiro, e com que frequência?Requisição/resposta, empurrão em uma direção, ou qualquer lado a qualquer momento. Decide como firewalls, balanceadores e tempos limite se comportam
4Tipos: existe um esquema, e quem o guarda?Nenhum (JSON), um documento (WSDL, OpenAPI) ou um contrato compilado (protobuf). Decide se uma mudança incompatível é pega no build ou às 3 da manhã
5Erros: como a falha é expressa?Um código de status, um documento de fault, um array de erros, um código de motivo. Decide se uma nova tentativa é segura e se um cliente distingue "não" de "não agora"
6Evolução: como se acrescenta um campo?Por regra, de forma aditiva; por uma nova versão na URL; por um novo namespace; ou não se acrescenta. Decide com que frequência você quebra alguém

Use as perguntas como uma lista de verificação. A tabela abaixo é o guia inteiro em uma tela; o resto dele preenche os detalhes.

ProtocoloDelimitaçãoEndereçamentoQuem falaEsquemaErrosUso típico
HTTP/1.1Content-Length ou chunkedURLo cliente pede, o servidor respondenenhum embutidocódigo de statustudo na web
HTTP/2 e /3frames binários por streamURLo cliente pede; muitos streams ao mesmo temponenhum embutidocódigo de status mais erros de streamo mesmo, mais rápido
REST sobre HTTPa do HTTPuma URL por recursoo clienteopcional (OpenAPI)código de status mais um corpoAPIs web públicas e internas
SOAPa do HTTP; o corpo é um envelope XMLum endpoint mais um nome de açãoo clienteWSDL e XSD, obrigatórioselemento Faultintegração corporativa, governo, legado
JSON-RPC 2.0a do HTTP, ou um fluxo de JSONnome do métodoo cliente, e notificaçõesnenhum embutidoobjeto error numéricoferramentas internas, nós de blockchain, editores
gRPCprefixo de 5 bytes por mensagem dentro de frames HTTP/2/package.Service/Methodos dois, com streaming em qualquer direçãoprotobuf, compiladostatus numérico nos trailersserviço a serviço dentro de um sistema
GraphQLa do HTTP; um POSTum endpoint, a consulta nomeia os dadoso clienteesquema, com introspecçãoarray errors, normalmente com HTTP 200uma API alimentando muitas telas diferentes
WebSocketo seu próprio cabeçalho de framea URL do upgradeos dois, a qualquer momentonenhum embutidocódigo de fechamentochat, jogos, painéis ao vivo
SSElinhas; uma linha em branco encerra um eventouma URLsó o servidor empurranenhumstatus HTTP na conexãocotações, progresso, notificações
Webhooka do HTTP, invertidaa sua URL no sistema deleseles chamam vocêo deleso seu código de statusintegrações entre empresas
AMQP 0-9-1frames bináriosexchange mais chave de roteamentobroker no meionenhumerros de canal e de conexãofilas de trabalho, integração corporativa
MQTTcabeçalho fixo de 2 bytes ou maistópicobroker no meionenhumcódigos de motivo (MQTT 5)IoT, celular, qualquer enlace ruim
SMTPpor linha; um . encerra os dadoscaixa postalo cliente empurra para um servidornenhumcódigos de resposta de três dígitose-mail, e nada mais hoje em dia
SFTPpacotes binários em um canal SSHcaminho de arquivoo clientenenhumcódigos de statustransferência de arquivos entre máquinas

2. HTTP: o substrato sobre o qual quase tudo se assenta

Em resumo. O HTTP é um protocolo de requisição e resposta com uma superfície quase textual, uma quantidade enorme de semântica acordada e uma infraestrutura de caches e proxies que só funciona se você usar o vocabulário dele corretamente.

O HTTP é especificado em partes: a semântica (métodos, códigos de status, cabeçalhos) na RFC 9110, a sintaxe do HTTP/1.1 na RFC 9112, o cache na RFC 9111, o HTTP/2 na RFC 9113 e o HTTP/3 na RFC 9114. As partes importam porque "HTTP" significa duas coisas diferentes em uma frase: o significado de uma requisição, que é o mesmo em todas as versões, e a forma como os bytes são escritos, que não é.

O que um cliente realmente envia

Isto é o que o curl colocou na rede para um GET contra um servidor local, como o servidor leu:

GET /orders/ord_7 HTTP/1.1\r\n
Host: 127.0.0.1:8731\r\n
User-Agent: curl/8.5.0\r\n
Accept: application/json\r\n
\r\n

Quatro linhas e uma linha em branco. Três coisas merecem atenção. O Host é obrigatório no HTTP/1.1, e é isso que torna possível a hospedagem virtual: um endereço, muitos sites. A linha vazia é a delimitação: os cabeçalhos terminam ali, e o que vem depois é o corpo. E o Accept é um desejo, não uma ordem; o servidor escolhe.

A resposta levou a sua própria delimitação e as suas regras de cache:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 27
ETag: "v3"
Cache-Control: max-age=60

{"id":"ord_7","total":4299}

A segunda requisição repetiu o GET com If-None-Match: "v3", e o servidor respondeu sem o corpo:

HTTP/1.1 304 Not Modified\r\n
ETag: "v3"\r\n
Cache-Control: max-age=60\r\n
\r\n

A resposta 200 tinha 131 bytes de cabeçalhos e corpo; a 304 tinha 68 bytes e nenhum corpo. É essa a ideia inteira de uma requisição condicional: o servidor prova que a cópia do cliente continua boa em vez de enviá-la outra vez. Em uma resposta de 2 MB a economia não é de 63 bytes, é de 2 MB, e custa um cabeçalho.

Delimitar sem um comprimento

Quando o servidor não sabe o tamanho de antemão, ele pode delimitar com blocos:

a\r\n
{"page":1}\r\n
a\r\n
{"page":2}\r\n
0\r\n
\r\n

Cada bloco é um comprimento em hexadecimal, os bytes e, por fim, um bloco de comprimento zero para encerrar. Vinte bytes de carga custaram 35 na rede aqui, que é o preço de poder começar a enviar antes de saber o total. É assim que o HTTP/1.1 faz streaming, e é por isso que um proxy que acumula respostas inteiras arruína APIs de streaming. HTTP/2 e HTTP/3 não usam codificação em blocos: eles têm os seus próprios frames, e Transfer-Encoding: chunked não é permitido ali.

A tabela de métodos, com as duas únicas palavras que importam

MétodoSeguroIdempotenteCorpoSignificado típico
GETsimsimsem semântica definidaler
HEADsimsimnãoler só os cabeçalhos
OPTIONSsimsimnãoo que posso fazer aqui (e a pré-verificação de CORS)
PUTnãosimsimsubstituir em um endereço conhecido
DELETEnãosimopcionalremover
POSTnãonãosimqualquer outra coisa: criar, agir, enviar
PATCHnãonão por definiçãosimmudança parcial (RFC 5789)

Seguro significa que a requisição não pretende alterar nada, então um rastreador ou um pré-carregamento pode emiti-la. Idempotente significa que fazê-la duas vezes tem o mesmo efeito que uma, que é exatamente a propriedade de que uma nova tentativa precisa. Um proxy, uma rede móvel ou a sua própria política de repetição vão repetir requisições, e o POST é o método em que isso pode cobrar duas vezes, e é por isso que existem chaves de idempotência (idempotência e efeitos exatamente uma vez).

O PATCH merece uma frase própria, porque o atalho comum "POST e PATCH não são idempotentes" mistura duas coisas diferentes. O método não é definido como idempotente: a RFC 5789 diz que o PATCH não é seguro nem idempotente, então um proxy, um gateway ou uma camada genérica de repetição não devem supor que repeti-lo é inofensivo. Se um patch específico é idempotente depende do que o documento de patch diz. {"op": "replace", "path": "/qty", "value": 5} chega ao mesmo estado por mais vezes que seja aplicado; {"op": "increment", "path": "/qty", "by": 1} não. Ou seja: o método não dá garantia nenhuma, os seus patches podem muito bem ter uma, e a única forma de um cliente saber qual é pela sua documentação ou por uma chave de idempotência que você aceite.

Conteúdo em um GET é outro tipo de armadilha. A delimitação da mensagem não o proíbe, mas a RFC 9110 afirma que conteúdo recebido em um GET não tem semântica geralmente definida: ele não pode alterar o significado nem o alvo da requisição, caches e proxies usam apenas o método e a URL como chave, e ele tem histórico suficiente como vetor de request smuggling para que alguns servidores e intermediários rejeitem a requisição de saída. "Os servidores ignoram" é o resultado habitual, não uma regra com que você possa contar, o que já é motivo para manter uma consulta na URL, ou usar POST e aceitar a perda de cache.

Códigos de status, lidos como um protocolo

A classe é a parte em que um cliente deve se basear para decidir, e o código específico é a parte que uma pessoa lê.

ClasseSignificado para um clienteCódigos que vale conhecer exatamente
1xxcontinue esperando, vem algo aí100 Continue, 101 Switching Protocols (o upgrade do WebSocket)
2xxfuncionou200, 201 com Location, 202 aceito e não concluído, 204 sem corpo
3xxprocure em outro lugar, ou você já tem301/308 permanente, 302/307 temporário, 304 não modificado
4xxa requisição está errada; não a repita sem mudanças400 malformada, 401 não autenticado, 403 autenticado e sem permissão, 404, 409 conflito, 412 precondição falhou, 422 entendida e semanticamente errada, 429 requisições em excesso
5xxo servidor falhou; uma nova tentativa pode funcionar500, 502 bad gateway, 503 indisponível (com Retry-After), 504 gateway timeout

Duas distinções carregam a maior parte do valor. 401 contra 403: a primeira diz "não sei quem você é", a segunda diz "sei, e não". 429 e 503 contra 500: as duas primeiras são convites a voltar, de preferência com Retry-After; uma 500 pelada não é, e repeti-la com força é como uma oscilação se transforma em indisponibilidade (padrões de resiliência).

Para o corpo de um erro, a RFC 9457 define o application/problem+json, que substituiu a RFC 7807:

{
  "type": "https://api.example.com/problems/insufficient-funds",
  "title": "Insufficient funds",
  "status": 409,
  "detail": "Account ends 4291 is short by EUR 12.40",
  "instance": "/transfers/t_8812",
  "balance_cents": 128760
}

O type é um identificador estável em que um cliente pode se basear, title e detail são para pessoas, e membros extras são permitidos. Usá-lo não custa nada e poupa cada cliente de interpretar a sua prosa.

Negociação de conteúdo, e o cabeçalho que torna o cache correto

O cliente declara preferências (Accept, Accept-Encoding, Accept-Language), o servidor escolhe uma e precisa então dizer de que a resposta dependeu:

Vary: Accept-Encoding, Accept-Language

Sem o Vary, um cache compartilhado pode entregar uma resposta em alemão comprimida a um cliente que pediu texto simples em inglês. Com Vary demais (User-Agent, por exemplo) a taxa de acerto do cache desaba. O cache em si é coberto em DNS, HTTP/2, HTTP/3 e CDNs.

As versões, em uma tabela

HTTP/1.1HTTP/2HTTP/3
Formato na redetexto, uma requisição por vez por conexãoframes binários, muitos streams por conexãoframes binários sobre QUIC
TransporteTCPTCPUDP, com o QUIC fornecendo streams e TLS 1.3
Compressão de cabeçalhosnenhuma (repita tudo)HPACKQPACK
Bloqueiouma resposta lenta bloqueia a conexão; navegadores abrem cerca de seisos streams são independentes no HTTP, mas um segmento TCP perdido trava todosum pacote perdido trava apenas o seu próprio stream
Server pushnãoespecificado, depois abandonado pelos navegadoresnão
Trailerstrailers em chunked, raramente suportadossim, e o gRPC depende delessim

O que isso significa na prática: o HTTP/1.1 recompensa requisições poucas e grandes e URLs amigáveis a cache; HTTP/2 e HTTP/3 tornam razoáveis muitas requisições pequenas, o que muda o desenho de APIs (o problema das cascatas de requisições). Nada acima muda o significado de um GET.

Onde o HTTP serve, e onde não

Ele serve para qualquer coisa que um cliente inicie, qualquer coisa que se beneficie de caches, proxies e ferramentas existentes, e qualquer coisa que tenha de atravessar uma rede estranha: a 443 é a única porta que sempre funciona. Ele não serve para mensagens iniciadas pelo servidor (seções 8 e 9), para chamadas internas muito conversadeiras em que o custo dos cabeçalhos domina (seção 5), nem para um dispositivo em um enlace de rádio tarifado enviando quatro bytes (seção 10).

3. REST: HTTP usado de propósito

Em resumo. REST não é "JSON sobre HTTP". É um conjunto de restrições cujo retorno prático é que a infraestrutura genérica entende a sua API: caches, proxies, novas tentativas e requisições condicionais funcionam porque o significado vive no método e na URL.

Roy Fielding descreveu o REST em 2000 como um estilo arquitetural com restrições: uma interface uniforme, ausência de estado, a separação cliente/servidor, capacidade de cache, camadas e código sob demanda. A parte que se paga diariamente é a interface uniforme. Quando "ler o pedido 7" é GET /orders/7, uma CDN pode guardá-lo em cache, um proxy pode repeti-lo, um navegador pode marcá-lo nos favoritos e uma linha de log conta o que aconteceu. Quando é POST /api com {"op":"getOrder","id":7}, nada disso funciona, e você tem uma API RPC vestida de REST.

Um exemplo compacto do vocabulário em uso:

POST /orders                       -> 201 Created, Location: /orders/7
GET /orders/7                      -> 200, ETag: "v3", Cache-Control: max-age=60
GET /orders/7 (If-None-Match "v3") -> 304 Not Modified
PUT /orders/7 (If-Match: "v3")     -> 200, or 412 if someone else changed it first
PATCH /orders/7                    -> 200, with a media type that says what a patch is
DELETE /orders/7                   -> 204, and 404 or 204 again if repeated
GET /orders?status=open&limit=50   -> 200, with a cursor for the next page

Dois padrões ali merecem ser copiados. O If-Match em uma escrita é concorrência otimista: a escrita falha com 412 em vez de sobrescrever em silêncio uma alteração feita no meio do caminho. E a URL da coleção leva os filtros como parâmetros de consulta, então o mesmo recurso pode ser guardado em cache por filtro.

As questões de desenho que vêm depois (modelagem de recursos, paginação, filtros, versionamento, respostas parciais, operações em lote) são o assunto de um guia próprio: desenhar uma API REST. Dois pontos pertencem aqui porque são pontos de protocolo, não de gosto:

Onde o REST serve, e onde não

Ele serve para APIs públicas, para qualquer coisa que um navegador toque, para qualquer coisa com uma longa cauda de clientes desconhecidos e para qualquer coisa que se beneficie de cache. Ele sofre quando uma tela precisa de doze recursos (a seção 7 responde a isso), quando as chamadas são internas e extremamente frequentes (seção 5) e quando a interação é de fato uma ação, e não uma coisa: POST /transfers é um recurso, mas "cancele este trabalho se ele ainda não começou" é um verbo, e vestir verbos de recurso é onde os desenhos REST ficam bobos.

4. SOAP e a família WS-*

Em resumo. O SOAP é um envelope XML com um contrato obrigatório legível por máquina (WSDL) e uma pilha de padrões opcionais para segurança, endereçamento e confiabilidade. Ele é verboso e antigo, continua em todo lugar em bancos, seguradoras, telecomunicações, saúde e governo, e a razão é o contrato, não a nostalgia.

Uma mensagem SOAP é um documento XML com uma forma fixa: um Envelope contendo um Header opcional e um Body obrigatório.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">urn:uuid:9e1f...</wsa:MessageID>
    <t:Transaction xmlns:t="urn:shop:tx" soap:mustUnderstand="true">8812</t:Transaction>
  </soap:Header>
  <soap:Body>
    <GetOrder xmlns="urn:shop:orders"><Id>ord_7</Id></GetOrder>
  </soap:Body>
</soap:Envelope>

Três detalhes aí explicam a maior parte do comportamento do SOAP.

As duas versões diferem de formas que quebram clientes

SOAP 1.1 (2000)SOAP 1.2 (Recomendação do W3C, 2007)
Namespace do envelopehttp://schemas.xmlsoap.org/soap/envelope/http://www.w3.org/2003/05/soap-envelope
Tipo de conteúdotext/xmlapplication/soap+xml
Qual operaçãoo cabeçalho HTTP SOAPAction separado, obrigatórioum parâmetro action no tipo de conteúdo (SOAPAction opcional)
Forma do faultfaultcode, faultstring, faultactor, detailCode com Value e Subcode, Reason com idioma, Detail
Códigos de faultClient, Server, VersionMismatch, MustUnderstandSender, Receiver, VersionMismatch, MustUnderstand, DataEncodingUnknown

Muitos endpoints em produção ainda são 1.1. Se um cliente envia um envelope 1.2 a um serviço 1.1, a resposta habitual é um fault VersionMismatch, e um SOAPAction ausente contra 1.1 muitas vezes produz um erro HTTP pelado em vez de um fault, que é a clássica situação do "funciona no SoapUI, mas não no meu código".

Um fault, na versão 1.2, e o código de status que o carrega:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <soap:Fault>
      <soap:Code><soap:Value>soap:Sender</soap:Value>
        <soap:Subcode><soap:Value xmlns:s="urn:shop:orders">s:UnknownOrder</soap:Value></soap:Subcode>
      </soap:Code>
      <soap:Reason><soap:Text xml:lang="en">No order with that id</soap:Text></soap:Reason>
      <soap:Detail><OrderId xmlns="urn:shop:orders">ord_7</OrderId></soap:Detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

No binding HTTP, um fault chega com HTTP 500 (um fault de remetente no SOAP 1.2 pode usar 400), que é a coisa mais confusa do SOAP para quem vem do REST: um erro de negócio perfeitamente bem tratado ("não existe esse pedido") é um HTTP 500. Um monitoramento que conta 5xx como "servidor quebrado" vai gritar diante de um serviço SOAP para sempre, a não ser que interprete o envelope.

WSDL: o contrato que é a razão de o SOAP sobreviver

Um documento WSDL 1.1 descreve o serviço em cinco partes: types (XML Schema para cada mensagem), message, portType (as operações), binding (como elas viajam: SOAP sobre HTTP, document/literal) e service (a URL do endpoint). Ele é legível por máquina de um jeito que o OpenAPI apenas aproxima, porque o esquema da carga é XSD: tipos, cardinalidade, enumerações, padrões, estruturas aninhadas, tudo validado pela pilha antes de o seu código rodar.

A consequência prática é a ferramentaria. Aponte um gerador para uma URL e receba código de cliente tipado:

# .NET
dotnet-svcutil https://partner.example.com/orders.svc?wsdl
# Java
wsimport -keep -p com.example.orders https://partner.example.com/orders?wsdl
# Python
python -m zeep https://partner.example.com/orders?wsdl        # inspect the operations
from zeep import Client                    # illustrative; zeep is a third-party library
client = Client("https://partner.example.com/orders?wsdl")
order = client.service.GetOrder(Id="ord_7")   # types, faults and the envelope are handled
print(order.TotalCents)

É essa a troca que o SOAP faz: muita cerimônia e, em troca, um contrato contra o qual os dois lados podem compilar, com uma incompatibilidade de versão pega por um validador de esquema em vez de por um nulo em produção.

Os padrões WS-* que você pode realmente encontrar

PadrãoO que acrescentaOnde você o vê
WS-Securitypartes da própria mensagem assinadas e cifradas, com X.509 ou tokens de usuário, independentemente do transportebancos, governo, qualquer lugar em que a mensagem precise continuar assinada depois de sair do túnel TLS
WS-Addressingids de mensagem e endpoints de resposta e de falha em cabeçalhosSOAP assíncrono, retornos de chamada, brokers no meio do caminho
WS-ReliableMessagingnúmeros de sequência e confirmações, com a garantia de entrega escolhida por sequência: no máximo uma vez, ao menos uma vez, exatamente uma vez ou em ordemintegrações de telecomunicações e de ERP sobre enlaces instáveis
WS-Policydeclarações legíveis por máquina do que um serviço exige (qual segurança, qual endereçamento)negociar com a pilha de um parceiro
MTOM / XOPanexos binários enviados como bytes de verdade em vez de base64 dentro do XMLdocumentos, imagens, radiografias

A segurança no nível da mensagem é a que não tem equivalente de uso comum no REST. O TLS protege o salto; uma assinatura WS-Security permanece com o documento através de uma fila, de um broker e de um arquivo, e um auditor pode verificá-la um ano depois. Quando um banco insiste em SOAP, normalmente é por isso.

Onde o SOAP serve, e onde não

Ele serve para uma integração com um parceiro em que um contrato precisa ser negociado, validado e auditado; em que a mensagem, não a conexão, precisa ser assinada; e em que o outro lado já o tem. Ele não serve para navegadores (interpretação de XML e sobrecarga de envelope sem ganho), para clientes móveis em enlaces tarifados, nem para qualquer serviço interno em que você controla as duas pontas. E ele não é motivo para evitar uma integração: clientes gerados fazem de chamar um serviço SOAP um dia de trabalho, não um trimestre.

5. RPC: chamar uma função que vive em outro lugar

Em resumo. Protocolos de RPC abrem mão de URLs e da semântica do HTTP e recebem de volta uma chamada de função tipada. O gRPC é o moderno: protobuf para os tipos, HTTP/2 para o transporte, streaming nas duas direções e status nos trailers.

A árvore genealógica é curta. O XML-RPC (1998) colocava um nome de método e parâmetros tipados em um pequeno documento XML. O JSON-RPC 2.0 (2010) fez o mesmo com JSON e continua sendo uma boa escolha quando você quer RPC sem um gerador de código:

--> {"jsonrpc":"2.0","method":"orders.get","params":{"id":"ord_7"},"id":1}
<-- {"jsonrpc":"2.0","result":{"id":"ord_7","total_cents":4299},"id":1}

--> {"jsonrpc":"2.0","method":"metrics.report","params":{"ok":true}}          // no id: a notification, no answer
<-- (nothing)

--> [{"jsonrpc":"2.0","method":"a","id":1},{"jsonrpc":"2.0","method":"b","id":2}]   // a batch

O seu objeto de erro usa códigos numéricos reservados, que é uma forma barata de distinguir um problema de protocolo de um de negócio:

CódigoSignificado
−32700JSON inválido
−32600não é um objeto de requisição válido
−32601método não encontrado
−32602parâmetros inválidos
−32603erro interno
−32000 a −32099reservados para os erros do seu próprio servidor

O JSON-RPC é agnóstico de transporte: os mesmos frames viajam sobre POST HTTP, um WebSocket, um pipe ou um socket TCP. É por isso que editores (o Language Server Protocol), nós Ethereum e muitos serviços internos o usam.

gRPC

O gRPC é um sistema de RPC com quatro partes que ficam mais fáceis de entender separadamente: protobuf para o contrato e os bytes (seção 6), HTTP/2 para o transporte, um modelo de chamada com quatro formatos e um modelo de status próprio.

O serviço é declarado e, depois, os dois lados geram código:

syntax = "proto3";
package shop;

service Orders {
  rpc GetOrder (GetOrderRequest) returns (Order);                    // unary
  rpc ListOrders (ListRequest) returns (stream Order);               // server streaming
  rpc ImportOrders (stream Order) returns (ImportSummary);           // client streaming
  rpc Watch (stream WatchRequest) returns (stream OrderEvent);       // bidirectional
}

Na rede, uma chamada unária é uma requisição HTTP/2 cujo caminho é o método e cujo corpo é uma sequência de mensagens com prefixo de comprimento:

:method = POST
:scheme = https
:path = /shop.Orders/GetOrder
content-type = application/grpc+proto
te = trailers
grpc-timeout = 2S                       <- the client's deadline travels with the call
authorization = Bearer ...              <- metadata is just HTTP/2 headers

Cada mensagem recebe um prefixo de cinco bytes: um byte dizendo se ela está comprimida, depois um comprimento big-endian de quatro bytes. Aqui está um de verdade, envolvendo o registro protobuf de 39 bytes da seção 6:

0000  00 00 00 00 27 0a 05 6f 72 64 5f 37 12 04 61 63  ....'..ord_7..ac
0010  6d 65 18 cb 21                                   me..!

00 significa não comprimido, 00 00 00 27 é 39, e o resto é a mensagem. Como o comprimento vem primeiro, o receptor sempre sabe onde uma mensagem termina, e é isso que torna direto transmitir muitas mensagens em uma chamada.

O status não viaja no corpo. Ele chega como trailers de HTTP/2, depois da última mensagem:

grpc-status: 0
grpc-message:

Esse desenho é o que permite a um servidor começar a transmitir resultados antes de saber se a operação inteira vai dar certo, e é também por isso que o gRPC precisa de HTTP/2 e por que um proxy que descarta trailers o quebra de um jeito doloroso de diagnosticar: os dados chegam, a chamada nunca se completa.

Os códigos de status são um conjunto pequeno e fixo, o que é uma vantagem real sobre "escolha um 4xx":

CódigoNomeRepetir?
0OK—
1CANCELLEDnão, quem chamou desistiu
3INVALID_ARGUMENTnão, corrija a requisição
4DEADLINE_EXCEEDEDtalvez, com um prazo maior
5NOT_FOUNDnão
6ALREADY_EXISTSnão, e muitas vezes significa que a sua primeira tentativa funcionou
7PERMISSION_DENIEDnão
8RESOURCE_EXHAUSTEDsim, com recuo
9FAILED_PRECONDITIONnão, até o estado mudar
10ABORTEDsim, normalmente um conflito de concorrência
12UNIMPLEMENTEDnão
13INTERNALnão, é um defeito
14UNAVAILABLEsim, com recuo
16UNAUTHENTICATEDnão, obtenha um token

Duas consequências práticas do desenho. Prazos fazem parte do protocolo: o grpc-timeout é enviado, propagado para as chamadas seguintes e respeitado nos dois lados, que é a disciplina de que a maioria das pilhas HTTP precisa ser convencida (tempos limite e novas tentativas). E um canal gRPC é uma conexão HTTP/2 de longa duração, então um balanceador no nível da conexão prende todas as chamadas a um backend; o balanceamento exige um proxy L7 ou balanceamento no cliente (balanceamento de carga, service meshes).

Navegadores não falam gRPC diretamente, porque não conseguem controlar frames de HTTP/2 nem ler trailers. O gRPC-Web resolve isso com uma delimitação um pouco diferente e um proxy que traduz; o streaming bidirecional não fica disponível.

Onde o RPC serve, e onde não

O gRPC serve para tráfego interno de serviço a serviço, taxas altas de chamada, equipes poliglotas que querem um contrato gerado e streaming nas duas direções. O JSON-RPC serve para ferramentas internas e para qualquer coisa que precise ser depurável à mão. O RPC não serve para APIs públicas com clientes desconhecidos (uma URL e o curl são uma porta de entrada melhor), para qualquer coisa que precise de cache HTTP, nem para uma equipe sem disposição para uma etapa de build e um registro de esquemas.

6. Esquemas e os bytes que eles produzem

Em resumo. O formato da carga decide tamanho, velocidade e se um campo errado é pego no build. O mesmo registro pequeno tem 39 bytes em protobuf, 122 em JSON compacto e 406 dentro de um envelope SOAP.

Um pedido com dois itens, serializado de três formas e depois comprimido com gzip (o script do apêndice produziu estes números; são tamanhos em bytes deste registro, não um teste de desempenho do seu tráfego):

FormatoBytesCom gzip
protobuf3957
JSON, compacto122118
envelope SOAP 1.2, XML406258

Note a surpresa honesta: o gzip deixa a mensagem protobuf maior, porque com 39 bytes o cabeçalho e o dicionário do gzip custam mais do que economizam. A compressão compensa em texto repetitivo, que é exatamente o que XML e JSON são. A diferença de 10x entre protobuf e XML cai para cerca de 4,5x quando os dois são comprimidos, e um único conjunto de cabeçalhos de resposta HTTP pode ser maior que qualquer um deles, razão pela qual a compressão de cabeçalhos do HTTP/2 importou tanto.

Como o protobuf chega a 39 bytes

Os bytes daquele registro, saídos da biblioteca de verdade:

0000  0a 05 6f 72 64 5f 37 12 04 61 63 6d 65 18 cb 21  ..ord_7..acme..!
0010  22 03 45 55 52 2a 07 0a 03 41 2d 31 10 02 2a 07  ".EUR*...A-1..*.
0020  0a 03 42 2d 39 10 01                             ..B-9..

Não há nomes de campo. Cada campo é um byte de tag que empacota o número do campo e um tipo de fio, depois o valor. 0a é o campo 1, tipo de fio 2 (delimitado por comprimento), então o que segue é um comprimento (05) e cinco bytes: ord_7. 18 cb 21 é o campo 3, tipo de fio 0 (varint), levando 4299.

Um varint guarda sete bits por byte e usa o bit mais alto para dizer "vem mais":

varint(1)    = 01
varint(300)  = ac 02
varint(4299) = cb 21

Números pequenos custam um byte, e é por isso que os números de campo de 1 a 15 cabem em um único byte de tag e por que o guia de estilo do protobuf diz para gastá-los nos campos que aparecem mais.

Os tipos de fio são a codificação inteira:

Tipo de fioUsado paraComo é delimitado
0int32, int64, uint*, bool, enumvarint
1fixed64, double8 bytes
2string, bytes, mensagens embutidas, campos repetidos empacotadoscomprimento em varint, depois tantos bytes
5fixed32, float4 bytes

(Os tipos de fio 3 e 4 eram os antigos marcadores de início e fim de grupo e estão obsoletos.)

As regras de evolução, que são o contrato de verdade

Como a rede leva números e não nomes, o protobuf tem regras claras de compatibilidade, e vale memorizá-las:

Compare como cada formato responde à pergunta 6 da seção 1:

FormatoOnde vive o esquemaAcrescentar um campoRemover umPego por
JSONem nenhum lugar, ou no OpenAPI ao ladoseguro, se os clientes ignoram extrasquebra quem o liatestes, ou a produção
XML com XSDo esquema, distribuídoexige mudança de esquema, muitas vezes um novo namespaceo mesmoum validador, antes do seu código
protobufo .proto, compilado nos dois ladosseguroseguro, se o número for reservadoo compilador, e uma verificação de registro de esquemas no CI
GraphQLo esquema do servidor, com introspecçãoseguro@deprecated, depois acompanhe o usoa verificação de esquema no CI

Esta é a diferença prática mais clara entre as famílias. O JSON compra velocidade de mudança e paga em incerteza; esquemas compilados compram certeza e pagam com uma etapa de build.

7. GraphQL: o cliente nomeia os dados

Em resumo. Um endpoint, um POST, uma linguagem de consulta que diz exatamente quais campos são desejados e um esquema que o cliente pode inspecionar. Resolve a busca excessiva e a tela de doze requisições, e move cache, autorização e controle de custo da infraestrutura para o seu código.

Uma consulta e a sua resposta:

query OrderScreen($id: ID!) {
  order(id: $id) {
    id
    totalCents
    customer { name email }
    items(first: 10) { sku qty }
  }
}
{ "data": { "order": { "id": "ord_7", "totalCents": 4299,
  "customer": { "name": "Acme", "email": "ops@acme.test" },
  "items": [ { "sku": "A-1", "qty": 2 }, { "sku": "B-9", "qty": 1 } ] } } }

A requisição é um POST de {"query": "...", "variables": {...}, "operationName": "OrderScreen"} para uma única URL, com content-type: application/json. Três consequências de protocolo vêm logo em seguida, e são elas que de fato fazem as pessoas tropeçarem.

Um campo que falha volta com HTTP 200. Uma resposta GraphQL pode levar data e errors juntos, porque um campo pode falhar enquanto o resto deu certo:

{ "data": { "order": { "id": "ord_7", "customer": null } },
  "errors": [ { "message": "Forbidden", "path": ["order","customer"],
                "extensions": { "code": "FORBIDDEN" } } ] }

O código de status, porém, não é sempre 200, e "o GraphQL sempre responde 200" é a simplificação que mete as equipes em apuros. A especificação separa um erro de requisição, em que o documento não pôde ser interpretado ou validado e nada foi executado, de um erro de campo, levantado durante a execução. Qual status você vê depende então do tipo de mídia da resposta:

application/json, o tipo tradicionalapplication/graphql-response+json, o tipo que a especificação recomenda
JSON malformado ou requisição ilegívelmuitas vezes 400400
Um documento que falha na validaçãoem geral 200, com errors e sem data400
Um erro de campo, com data parcial200200
Método errado, ou um tipo de mídia que o servidor não aceita405, 415405, 415

Leia "muitas vezes" e "em geral" ao pé da letra: o GraphQL sobre HTTP ainda é um rascunho, revisões posteriores mudam alguns desses códigos e os servidores diferem, então confira o que o seu realmente faz em vez de confiar em uma tabela. O que vale em todo lugar é a consequência: um cliente que decide apenas pelo status HTTP não percebe erros de campo, e um painel que conta respostas que não são 2xx pode mostrar um serviço impecável enquanto cada requisição volta falhando pela metade. Coloque o seu código legível por máquina em extensions, alerte pela proporção de respostas que contêm errors e peça o tipo de mídia mais novo se você quiser que a linha de status carregue informação.

O cache HTTP não se aplica. Um POST para uma URL com um corpo que muda por tela não é cacheável por nenhuma CDN ou cache de navegador. As respostas são consultas persistidas (registre a consulta uma vez, envie um hash), GET para consultas seguras de guardar em cache e cache dentro do servidor, no nível do resolvedor ou da entidade.

A consulta é uma superfície de ataque. Um cliente pode pedir um grafo profundo e caro. As proteções são limites de profundidade, análise de complexidade ou de custo com um orçamento por chamador, argumentos de paginação obrigatórios em vez de opcionais, consultas persistidas em produção (para só rodar consultas conhecidas) e tempos limite por resolvedor.

O outro problema famoso é o N+1: uma lista de 50 pedidos cujo campo customer dispara 50 consultas ao banco. A correção é agrupar na camada de resolvedores (no estilo do DataLoader: colete os ids pedidos em um mesmo ciclo, busque-os em uma consulta e entregue a cada resolvedor a sua parte). Isso é uma questão de desenho do servidor, não do protocolo, mas é a primeira coisa a procurar quando uma API GraphQL está lenta.

As subscriptions não fazem realmente parte do protocolo. A especificação define o tipo de operação, não o transporte. Na prática, as subscriptions rodam sobre um WebSocket com um subprotocolo (graphql-transport-ws, que substituiu o antigo subscriptions-transport-ws) ou sobre SSE. Isso significa que os alertas da seção 8 sobre conexões de longa duração também valem para as subscriptions do GraphQL.

Onde o GraphQL serve, e onde não

Ele serve para vários clientes diferentes com necessidades de dados diferentes sobre um mesmo backend, para um aplicativo móvel que precisa minimizar idas e voltas, e para uma organização disposta a cuidar do esquema como um produto. Ele não serve para um serviço CRUD simples com um cliente (não compra nada e custa um servidor), para envio e download de arquivos (o HTTP já faz isso bem), nem para uma equipe que precisa de cache de CDN para sustentar a carga.

8. Quando o servidor precisa falar primeiro: WebSocket, SSE e long polling

Em resumo. A forma do HTTP é "o cliente pede". Três técnicas contornam isso: manter uma requisição aberta (long polling), transmitir um canal de texto em uma só direção (SSE) ou trocar a conexão HTTP por um protocolo de frames em duas direções (WebSocket). Escolha a mais fraca que resolva, porque toda conexão de longa duração é uma coisa a operar.

WebSocket

Um WebSocket começa como uma requisição HTTP comum e então deixa de ser HTTP:

GET /live HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: AAECAwQFBgcICQoLDA0ODw==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: graphql-transport-ws
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: Bz3qJYTGdOe8gUSpLosEdiLKDrk=
Sec-WebSocket-Protocol: graphql-transport-ws

Aquele valor de Sec-WebSocket-Accept não é um segredo nem um token. Ele é base64(sha1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")), com esse GUID fixo da RFC 6455. O par acima foi calculado pelo script do apêndice, então você pode conferir. A única função dele é provar que o servidor entendeu o upgrade, em vez de devolver bytes como um proxy bobo, o que também explica por que não faz sentido "validá-lo" por segurança.

Depois do 101 não há mais cabeçalhos, só frames. Um frame de texto do cliente levando {"op":"subscribe"}:

0000  81 92 a3 1f 00 7c d8 3d 6f 0c 81 25 22 0f d6 7d  .....|.=o..%"..}
0010  73 1f d1 76 62 19 81 62                          s..vb..b

81 é FIN mais o opcode 1 (texto). 92 é o bit de máscara mais o comprimento 18. Os quatro bytes seguintes são a chave de mascaramento, e o resto é a carga com XOR aplicado; desmascarar devolve exatamente o JSON original. Então o custo é de seis bytes em um frame do cliente (2 de cabeçalho + 4 de máscara) e dois em um frame do servidor, contra algo entre 100 e 800 bytes de cabeçalhos em uma requisição HTTP. É esse o verdadeiro argumento a favor do WebSocket: não que ele seja mais rápido, mas que uma mensagem custa quase nada depois que a conexão existe.

Os detalhes de frame que vale conhecer:

CampoValores
Opcodes0x0 continuação, 0x1 texto, 0x2 binário, 0x8 fechamento, 0x9 ping, 0xA pong
Mascaramentoobrigatório nos frames do cliente para o servidor, proibido nos do servidor para o cliente. Existe para impedir que uma carga forjada envenene um proxy antigo
Comprimento0 a 125 embutido; 126 significa que vem um comprimento de 2 bytes; 127, de 8 bytes
Códigos de fechamento1000 normal, 1001 saindo, 1002 erro de protocolo, 1008 violação de política, 1009 mensagem grande demais, 1011 erro interno. O 1006 significa "a conexão morreu" e nunca é enviado na rede
Extensõespermessage-deflate (RFC 7692) comprime as cargas; custa memória por conexão

O que o protocolo não lhe dá, e você portanto tem de construir:

A RFC 8441 permite WebSocket sobre HTTP/2 via CONNECT estendido, o que remove o custo de uma conexão por socket; o suporte é irregular. Sobre HTTP/3, a opção voltada ao futuro é o WebTransport, que acrescenta datagramas não confiáveis para casos em que uma mensagem atrasada é pior que uma perdida, como jogos.

Server-sent events

Se o tráfego só flui em uma direção, o SSE dá um décimo do trabalho. Ele é uma resposta HTTP comum que nunca termina:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-store

id: 41
event: price
data: {"sym":"ACME","p":12.5}

retry: 5000

: keep-alive comment

As regras cabem em um cartão-postal: os campos são data, event, id e retry; uma linha em branco despacha o evento; uma linha que começa com : é um comentário usado como batimento. O EventSource do navegador reconecta por conta própria e envia o Last-Event-ID com o id que viu por último, então um servidor que respeite esse cabeçalho dá fluxos retomáveis de graça. É só texto (UTF-8), em uma direção, e em HTTP/1.1 ocupa uma das seis conexões que um navegador permite por origem, que é a razão habitual de uma página com SSE misteriosamente parar de carregar outras coisas. Em HTTP/2 o fluxo é um entre muitos em uma única conexão, então esse gargalo desaparece, mas não todo limite: o teto passa a ser o limite de streams concorrentes que o servidor anuncia em SETTINGS_MAX_CONCURRENT_STREAMS, normalmente na casa das centenas baixas.

Long polling, e quando ele é a escolha certa

O cliente envia uma requisição; o servidor a mantém aberta até haver novidade ou estourar o tempo limite; o cliente pergunta de novo em seguida. É feio, funciona através de todo proxy já construído e não precisa de infraestrutura nova. Para uma notificação que chega algumas vezes por hora é uma resposta perfeitamente razoável, e continua sendo o plano B que toda biblioteca de tempo real entrega.

Long pollingSSEWebSocket
Direçãoservidor para cliente, uma mensagem por requisiçãoservidor para cliente, contínuonas duas direções
TransporteHTTP puroHTTP puroupgrade de HTTP, depois frames
Cargaqualquer coisatexto UTF-8texto ou binário
Reconectar e retomarvocê escreveembutido (Last-Event-ID)você escreve
Problemas com proxy e firewallquase nenhumpoucos (atenção ao buffer de resposta)alguns (o upgrade precisa ser permitido, tempos limite de inatividade)
Custo por mensagemuma requisição e uma resposta completasalguns bytes2 a 6 bytes
Bom paranotificações rarascotações, progresso, logs, feedschat, colaboração, jogos, negociação

O padrão honesto: SSE até você precisar enviar para cima, e então WebSocket. A maioria dos projetos que dizem "precisamos de WebSockets" é um feed de uma direção mais POSTs ocasionais, e essa combinação é mais simples de operar, depurar e guardar em cache.

9. Webhooks: HTTP com a flecha invertida

Em resumo. Um webhook é o sistema de outra pessoa fazendo uma requisição HTTP para a sua URL quando algo acontece. O protocolo é trivial; a engenharia está toda em assinaturas, novas tentativas, ordem e idempotência.

POST /hooks/payments HTTP/1.1
Host: shop.example.com
Content-Type: application/json
Webhook-Id: evt_9f21
Webhook-Timestamp: 1762790400
Webhook-Signature: v1,k3Jp8Qn...=

{"type":"payment.succeeded","id":"evt_9f21","data":{"amount_cents":4299}}

A lista de verificação do receptor, em ordem, porque a ordem importa:

  1. Verifique a assinatura sobre os bytes brutos, antes de interpretar. O esquema habitual é HMAC-SHA256 sobre o id, o carimbo de tempo e o corpo exato, com um segredo compartilhado. Serializar o JSON de novo antes muda os bytes e quebra a verificação.
  2. Rejeite carimbos de tempo antigos (uma janela de alguns minutos), ou uma requisição capturada pode ser repetida para sempre.
  3. Responda 2xx rapidamente e então trabalhe. Remetentes estouram o tempo limite em segundos. Guarde o evento e processe-o de forma assíncrona; não rode o faturamento dentro do tratador.
  4. Elimine duplicatas pelo id do evento. Repetições, entrega ao menos uma vez e os seus próprios 500 significam que o mesmo evento vai chegar duas vezes (idempotência).
  5. Não presuma ordem. O payment.succeeded pode chegar antes do order.created. Ou você tolera isso, ou busca o estado atual na API do remetente e trata o webhook puramente como um empurrãozinho: o padrão de "carga magra", que também evita confiar em dados que você não buscou.
  6. Espere que o seu endpoint seja sondado. Valide o tipo de conteúdo e o tamanho, limite o corpo e mantenha o tratador livre de qualquer coisa que rode sobre entrada não confiável (segurança de aplicações web).

Do lado de quem envia, as obrigações são espelhadas: repetir com recuo exponencial e um teto, mostrar ao cliente um registro de entregas com os códigos de resposta, assinar cada tentativa, permitir a rotação do endpoint com dois segredos válidos durante a troca e desativar um endpoint que falha há dias em vez de martelá-lo. Se você não pode ser chamado de volta de jeito nenhum (sem URL pública), as opções restantes são consultar com um cursor ou um broker de mensagens que os dois lados alcancem (seção 10).

10. Protocolos de mensageria: AMQP, MQTT, STOMP

Em resumo. Estes protocolos põem um broker entre quem envia e quem recebe, então os dois nunca precisam estar online ao mesmo tempo. O AMQP é o protocolo corporativo de filas de trabalho, o MQTT é o protocolo de dispositivos pequenos, o STOMP é o de texto simples. O que eles compram é desacoplamento; o que custam é um broker para operar e um conjunto novo de modos de falha.

Os padrões, as garantias de entrega e o lado operacional são cobertos em filas de mensagens e garantias de entrega. Esta seção é sobre os protocolos em si.

AMQP 0-9-1, e a pegadinha no número da versão

O AMQP 0-9-1 é o que o RabbitMQ fala (porta 5672, 5671 com TLS). O seu modelo tem três substantivos: um publicador envia para um exchange com uma chave de roteamento; bindings conectam exchanges a filas; consumidores leem das filas. Os tipos de exchange decidem o roteamento: direct (chave exata), topic (padrões como orders.*.eu), fanout (para todos) e headers. Uma conexão TCP leva muitos canais, então um processo não precisa de uma conexão por thread.

Os recursos do protocolo que importam em produção:

O AMQP 1.0 é um protocolo diferente com o mesmo nome. Ele foi padronizado pela OASIS e como ISO/IEC 19464, e descreve pares simétricos trocando mensagens por links com controle de fluxo baseado em crédito, não o modelo de exchange e fila. O Azure Service Bus e o ActiveMQ o falam; um cliente 0-9-1 não consegue conversar com um broker que só tem 1.0. Quando alguém diz "é AMQP, então vai interoperar", pergunte qual versão.

MQTT, para enlaces que você não controla

O MQTT (porta 1883, 8883 com TLS) foi desenhado para dispositivos em enlaces lentos, caros e instáveis, e o desenho aparece na contagem de bytes. Um pacote CONNECT completo, construído à mão no script do apêndice:

0000  10 15 00 04 4d 51 54 54 04 02 00 3c 00 09 73 65  ....MQTT...<..se
0010  6e 73 6f 72 2d 31 37                             nsor-17

10 é o tipo de pacote (CONNECT), 15 é o comprimento restante (21 bytes), depois o nome do protocolo MQTT, o nível 4 (que significa MQTT 3.1.1), os sinalizadores, um keep-alive de 60 segundos e o id do cliente. Uma publicação de uma leitura de temperatura com QoS 1:

0000  32 14 00 0c 70 6c 61 6e 74 2f 33 2f 74 65 6d 70  2...plant/3/temp
0010  00 01 32 31 2e 35                                ..21.5

Vinte e dois bytes levam o tópico, um id de pacote e a leitura 21.5; a confirmação (PUBACK) tem quatro bytes. O POST HTTP/1.1 mais enxuto possível com os mesmos quatro bytes tem 103 bytes, antes de qualquer resposta, qualquer TLS e qualquer nova tentativa. Em um sensor a bateria reportando a cada minuto por um enlace celular, essa proporção é a decisão de produto.

As partes do MQTT que você precisa entender antes de usá-lo:

RecursoO que fazA pegadinha
QoS 0dispare e esqueçaperdida a qualquer soluço, e isso muitas vezes está bem para um sensor
QoS 1ao menos uma vez, com confirmaçãoduplicatas, então o receptor precisa ser idempotente
QoS 2exatamente uma vez, handshake de quatro etapaso mais lento e com mais estado por mensagem; raramente vale a pena
Mensagem retidao broker guarda a última mensagem por tópico e a dá a novos assinantesnão é histórico, só o valor mais recente, e persiste até ser substituído
Último desejoo broker publica uma mensagem se um cliente desaparecera única forma de os outros saberem que um dispositivo ficou offline
Keep-aliveum intervalo de batimento acordado no CONNECTuma regra de bolso é o cliente usar metade do intervalo no seu próprio timer
Sessão limpa / expiração de sessãose assinaturas e mensagens enfileiradas sobrevivem a uma desconexãouma sessão persistente em um tópico movimentado pode fazer o broker guardar muita coisa
Curingas+ casa com um nível, # casa com o resto e precisa vir por último# na raiz assina tudo, inclusive os tópicos de outros inquilinos

Vale pedir o MQTT 5: ele acrescenta códigos de motivo em cada confirmação (então uma publicação recusada diz por quê), propriedades de usuário (cabeçalhos arbitrários de chave e valor, onde mora um id de correlação), assinaturas compartilhadas ($share/group/topic, para um tópico ser balanceado entre trabalhadores), aliases de tópico, expiração de mensagem e controle de fluxo de verdade. O MQTT 3.1.1 responde à maioria das falhas com uma conexão fechada e nenhum motivo.

Note o que o MQTT não tem: nenhum esquema, nenhuma requisição e resposta (o MQTT 5 acrescenta uma convenção de tópico de resposta), nenhuma garantia de ordem entre tópicos, e a autorização é tarefa do broker, normalmente por padrão de tópico. O desenho dos tópicos é o desenho da API, e é também a fronteira de segurança: tenant/{id}/# é o padrão que mantém os inquilinos separados.

STOMP, e o protocolo do Kafka

O STOMP é um protocolo de texto (CONNECT, SEND, SUBSCRIBE, MESSAGE, ACK) que se parece com HTTP e é trivial de implementar. A sua casa comum é um navegador falando com um broker por um WebSocket, que é o que a pilha de mensageria do Spring faz.

O Kafka não fala AMQP nem MQTT. Ele tem o seu próprio protocolo TCP binário, com prefixo de comprimento, e o modelo é diferente o bastante para importar: um log append-only particionado com offsets gerenciados pelos consumidores, em vez de filas que se esvaziam. Escolher entre uma fila e um log é uma decisão de arquitetura, não de protocolo; o guia de filas cobre isso.

Onde a mensageria serve, e onde não

Ela serve para trabalho que pode levar mais tempo que uma requisição, para picos de tráfego que precisam ser absorvidos, para vários consumidores de um evento, para sistemas que não estão de pé ao mesmo tempo e para dispositivos em enlaces ruins. Ela não serve para um cliente esperando uma resposta agora (uma fila mais uma fila de resposta é um RPC lento e frágil), para chamadas internas simples entre dois serviços que você implanta juntos, nem para qualquer equipe que não esteja pronta para monitorar profundidade de fila e atraso de consumidor.

11. Os sobreviventes: SMTP, IMAP, FTP, SFTP e SSH

Em resumo. E-mail e transferência de arquivos são os protocolos que você herda, não os que escolhe. Eles valem uma página porque os modos de falha são específicos, antigos e ainda custam dias às pessoas.

SMTP

O SMTP (RFC 5321) é uma conversa por linhas em que cada resposta é um código de três dígitos. A forma de uma submissão:

S: 220 mail.example.com ESMTP ready
C: EHLO shop.example.com
S: 250-mail.example.com
   250-SIZE 36700160
   250-STARTTLS
   250 PIPELINING
C: STARTTLS            -> then the whole conversation restarts inside TLS
C: MAIL FROM:<orders@shop.example.com>
S: 250 OK
C: RCPT TO:<ops@acme.test>
S: 250 OK
C: DATA
S: 354 Start mail input; end with <CRLF>.<CRLF>
C: (headers, blank line, body)
C: .
S: 250 OK id=1A2B3C

Os detalhes que causam incidentes de verdade:

Ler e-mail é outro protocolo: o IMAP (IMAP4rev2, RFC 9051; portas 143 e 993) mantém as mensagens no servidor com pastas, marcações e busca no servidor, enquanto o POP3 (110 e 995) é um modelo de baixar e apagar, de uma época em que uma pessoa usava um computador.

FTP, FTPS, SFTP, SCP

O FTP (RFC 959) usa duas conexões: um canal de controle na porta 21 para comandos e uma conexão de dados separada por transferência. É esse todo o problema dele. No modo ativo, o servidor conecta de volta a uma porta que o cliente informa com PORT, o que praticamente nenhum firewall ou NAT permite hoje; no modo passivo (PASV, ou EPSV para IPv6), o servidor informa uma porta e o cliente conecta, o que funciona, mas exige que o servidor exponha uma faixa de portas. Metade de todos os atendimentos de FTP é "a listagem funciona, a transferência fica pendurada", e isso é o modo ativo encontrando um NAT.

FTPSSFTPSCP
O que éFTP com TLS (AUTH TLS, RFC 4217)um subsistema de transferência de arquivos do SSH, na porta 22um comando de cópia, historicamente um protocolo próprio
Relação com o FTPo mesmo protocolo, cifradonão relacionado, apesar do nomenão relacionado
Portas21 mais uma faixa de dadosuma, a 2222
Amizade com firewallsruim (a faixa de dados)boaboa
Recursoslistagem de diretório, retomadalistagem, retomada, atributos, leituras e escritas parciaissó cópia

O conselho prático é curto: use SFTP. É uma porta, autenticado e cifrado pelo SSH, roteirizável, e é o que parceiros querem dizer hoje quando falam "FTP". O OpenSSH 9.0 até fez o scp usar o protocolo SFTP por baixo, porque o antigo protocolo SCP tinha um longo histórico de surpresas. Use FTPS só quando o outro lado insistir, e, se você tiver de rodar um servidor FTP, rode em modo passivo com uma faixa fixa e aberta de portas e registre em log qual modo cada cliente usou.

SSH, por baixo de tudo isso

O SSH (RFC 4251 a 4254) tem três camadas: uma de transporte, que negocia algoritmos, troca chaves e autentica o servidor com a sua chave de host; uma de autenticação do usuário (chave pública, senha, teclado interativo); e uma de conexão, que multiplexa canais sobre o único fluxo cifrado. Canais são o motivo de uma conexão SSH poder levar um shell, uma transferência de arquivos e três portas encaminhadas ao mesmo tempo.

Duas coisas decorrem dessa estrutura. A verificação da chave de host é confiança no primeiro uso: a impressão digital guardada em known_hosts na primeira conexão é o que depois avisa sobre alguém no meio do caminho, então aceitar uma chave alterada às cegas joga fora a principal garantia do protocolo. E o encaminhamento de portas (-L, -R, -D) é um canal como qualquer outro, e é por isso que o SSH é a ferramenta universal para alcançar um banco de dados que não está exposto, e também a primeira coisa que uma revisão de segurança olha.

12. As preocupações que atravessam todos eles

Em resumo. Portas, autenticação, vocabulário de erros, versionamento, rastreamento e o que medir têm aparência diferente em cada protocolo, mas são os mesmos seis problemas. Conhecer o mapeamento é a maior parte do que significa "ter experiência com protocolos".

Portas, em uma tabela

ProtocoloSem TLSCom TLSObservação
HTTP80443a 443 é a única porta com que você pode contar para atravessar uma rede corporativa
WebSocket80 (ws://)443 (wss://)é HTTP até o 101
gRPC—443, ou qualquer porta internamenteé HTTP/2, então as mesmas portas do HTTP
SMTP25 relay, 587 submissão465 submissão, ou STARTTLS na 587a 25 de saída é bloqueada em quase todo lugar
IMAP / POP3143 / 110993 / 995
FTP21 mais dados21 com AUTH TLS (FTPS)o problema é o canal de dados, não a porta
SSH, SFTP2222 (o SSH é sempre cifrado)uma porta para shell, transferência e encaminhamento
AMQP 0-9-156725671a interface de gestão do RabbitMQ é a 15672, outra coisa
MQTT18838883MQTT sobre WebSocket usa as portas web, ou uma que o broker escolha
DNS53853 (DoT), 443 (DoH)veja o guia de DNS

Autenticação, por protocolo

ProtocoloMecanismos usuaisA aresta afiada
HTTP, REST, GraphQLAuthorization: Bearer (RFC 6750), Basic (RFC 7617), cookies, chaves de API, TLS mútuoum token em um parâmetro de consulta acaba em logs, caches e cabeçalhos Referer
gRPCcabeçalhos de metadados (authorization), ou TLS mútuo com credenciais por canalos metadados são por chamada, mas um canal é de longa duração: renovar tokens exige uma credencial no momento da chamada, não no da conexão
SOAPcabeçalhos WS-Security (token de usuário, assinatura X.509), ou HTTP Basic com TLSassinaturas no nível da mensagem sobrevivem a brokers e arquivos; autenticação de transporte não
WebSocketcookie no handshake, token na primeira mensagem, ou um tíquete de curta duração na URLnavegadores não conseguem definir cabeçalhos no handshake, então o desenho é forçado
AMQP, MQTTusuário e senha na conexão, certificados de cliente, ACLs do broker por fila ou tópicoa autorização é do broker, não da aplicação: acerte os padrões de tópico ou de fila
SMTPSASL na porta de submissãoa autenticação diz quem pode enviar, não qual endereço pode alegar
SSH, SFTPchave pública, certificados, (senhas)a chave de host é a única proteção do cliente; uma mudança aceita é um atacante aceito

Sessões, tokens e os seus tempos de vida são um assunto próprio: autenticação e sessões.

A mesma falha, dita de seis maneiras

Esta é a tabela que eu queria ter quando comecei. Uma linha é uma situação real, e as colunas são como cada protocolo a expressa.

SituaçãoHTTP / RESTgRPCGraphQLJSON-RPCSOAPMQTT 5
Requisição malformada4003 INVALID_ARGUMENT400, ou 200 com errors e sem data (seção 7)−32600 / −32602fault Sendercódigo de motivo 0x81
Não autenticado40116 UNAUTHENTICATED200 com um erro de autenticaçãoprópriofault de segurança0x87 na conexão
Autenticado, sem permissão4037 PERMISSION_DENIEDerrors com um caminho e campo nuloprópriofault Sender0x87 na publicação
A coisa não existe4045 NOT_FOUNDnull mais um erroprópriofault de aplicação—
Conflito com o estado atual409 / 41210 ABORTED, 9 FAILED_PRECONDITIONerrorsprópriofault de aplicação—
Requisições em excesso429 com Retry-After8 RESOURCE_EXHAUSTEDerrorspróprio0x97 cota excedida—
O servidor quebrou50013 INTERNALerrors−32603fault Receiver—
Temporariamente fora503 com Retry-After14 UNAVAILABLEerrors−32603fault Receiverconexão fechada
Demorou demais5044 DEADLINE_EXCEEDEDerrorstempo limitetempo limitetempo limite de keep-alive

Leia as colunas e aparecem duas lições de protocolo. Primeiro, os protocolos que separam "não repita" de "repita mais tarde" tornam os clientes muito mais fáceis de escrever: o HTTP (4xx contra 429 e 503) e o gRPC (INVALID_ARGUMENT contra UNAVAILABLE) separam; o GraphQL e o MQTT 3.1.1 em geral não, então você precisa codificar isso você mesmo, em extensions ou em um campo da carga. A linha de status do GraphQL diz algo só depois que você negocia o tipo de mídia mais novo, e mesmo assim apenas sobre erros de requisição. Segundo, um protocolo que responde 200 ou fecha a conexão para tudo força cada cliente a interpretar prosa, e é assim que as tempestades de novas tentativas começam.

Versionamento, por protocolo

ProtocoloComo uma versão é expressaMudança aditivaMudança incompatível
RESTcaminho (/v2/orders), tipo de mídia (application/vnd.shop.v2+json) ou um cabeçalhoacrescente um campo, ignore os desconhecidosuma nova versão, as duas servidas por um tempo
GraphQLnormalmente nenhuma: um esquema em evoluçãoacrescente campos e tipos@deprecated, meça o uso, depois remova
gRPC, protobufo nome do pacote (shop.v2)acrescente um campo com um número novoum novo serviço ou pacote; nunca reuse um número de campo
SOAPum novo namespace de destino e uma nova URL de WSDLum novo elemento opcional, se o esquema permitirum novo namespace; o antigo continua rodando
JSON-RPCo nome do método (orders.get.v2)acrescente um parâmetro opcionalum novo nome de método
MQTT, AMQPo tópico ou a chave de roteamento, e um campo de versão na cargaum campo novo, se o consumidor tolerarum novo tópico, com os dois publicados durante a troca

O padrão em todos eles: acrescentar é barato, remover é um projeto. Todo protocolo acima dá uma forma de acrescentar e uma forma de rodar duas versões em paralelo; nenhum dá uma forma de apagar algo que os clientes ainda usam.

Correlação e rastreamento

Um campo, levado a todo lugar, é o que torna uma requisição rastreável entre protocolos. O cabeçalho do W3C Trace Context é a forma comum:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
ProtocoloPara onde ele vai
HTTP, REST, GraphQLo cabeçalho traceparent
gRPCmetadados, que são cabeçalhos HTTP/2, então o mesmo nome
AMQPum cabeçalho de mensagem ou propriedade de aplicação
MQTT 5uma propriedade de usuário; no 3.1.1 não há lugar além da carga
SOAPum elemento de cabeçalho, normalmente o MessageID do WS-Addressing
Webhooksum cabeçalho que o remetente define; registre o id de evento dele além do seu

A razão para se importar é que uma requisição que atravessa quatro protocolos sem um id compartilhado são quatro investigações separadas (observabilidade).

O que medir, por protocolo

Nenhum guia pode dizer os seus números. Pode dizer quais quatro sinais merecem um painel.

ProtocoloAcompanhe
HTTP, RESTtaxa de requisições, percentis de latência por rota, taxas por classe de status e a proporção de 304 e de acertos de cache
GraphQLa proporção de respostas que levam errors, o tempo de resolvedor por campo, a profundidade e o custo das consultas e as consultas mais caras
gRPCcontagens por código de status (não só a taxa de erro), a proporção de prazos excedidos, os tamanhos de mensagem e a distribuição de chamadas por conexão
WebSocket, SSEconexões abertas, conexões por nó, taxa de mensagens, falhas de ping e profundidade do buffer de envio
Webhooks (envio)sucesso de entrega, tentativas por evento, idade do evento pendente mais antigo, endpoints desativados
AMQP, MQTTprofundidade de fila e atraso do consumidor, contagens de reentrega, mensagens em dead-letter e memória do broker
SMTPaceitos contra postergados contra devolvidos, e relatórios de DMARC

13. Escolher

Em resumo. Escolha por quem começa a conversa, quem são os clientes e quão rígido o contrato precisa ser. Nessa ordem.

Diagram: Choosing a protocol

A mesma coisa em uma tabela, com o custo que você está aceitando:

SituaçãoUseO que você aceita
Uma API pública ou voltada a parceirosREST sobre HTTP com JSONnenhuma imposição de esquema, a não ser que você acrescente OpenAPI e o verifique no CI
Chamadas internas, muitas por segundo, em várias linguagensgRPCuma etapa de build, um registro de esquemas e proxies que precisam lidar com trailers de HTTP/2
Um backend, vários front ends muito diferentesGraphQLcache, controle de custo e autorização passam a ser o seu código
Um banco, uma seguradora, um órgão de governo do outro ladoSOAPverbosidade, e 5xx em erros de negócio
Atualizações ao vivo para um navegadorSSE, e WebSocket se você precisar enviar para cimaconexões de longa duração para operar e escalar
Outra empresa precisa lhe contar sobre eventoswebhooksverificação de assinatura, repetições, duplicatas e nenhuma ordem
Trabalho que não pode ser perdido e pode ser lentoAMQP ou um logum broker para operar, e profundidade de fila para acompanhar
Dispositivos a bateria ou em enlace tarifadoMQTTnenhum esquema, e o desenho de tópicos como fronteira de segurança
Arquivos entre empresasSFTPgestão de chaves, e uma transferência que não é uma transação
E-mailSMTP, por um provedorentregabilidade é DNS e reputação, não código

Três padrões que vale enunciar com clareza, porque são os que poupam mais tempo:

Migrar sem reescrever

DeParaO caminho habitual
SOAPREST ou gRPCmantenha o endpoint SOAP, acrescente o novo na frente da mesma camada de serviço, mova os clientes um por um e mantenha um cliente SOAP gerado para os parceiros que nunca vão migrar
RESTgRPC internamenteintroduza-o em um par de serviços conversadeiro, mantenha REST na borda; um gateway pode traduzir (grpc-gateway, Envoy)
Consultas REST periódicasSSE ou WebSocketentregue primeiro o SSE para o feed e mantenha a consulta periódica como plano B; o código de cliente dos dois é parecido
Consultar um parceirowebhooksaceite webhooks como um empurrãozinho e mantenha o trabalho de consulta em baixa frequência como rede de segurança
Uma fila usada como RPCgRPC ou HTTPse quem chama espera a resposta, nunca foi mensageria

14. Erros comuns

15. O que mencionar em uma entrevista

Resumo rápido

Apêndice: o script de demonstração

Tudo o que foi citado como bytes neste guia saiu de um script: protocols.py, Python 3.13 e a biblioteca padrão, mais o curl para a parte de HTTP e o pacote protobuf para a única verificação cruzada de que uma biblioteca de verdade interpreta os bytes mostrados. Ele sobe um servidor HTTP local em 127.0.0.1, então não toca a rede, e imprime cada troca, hex dump e contagem de bytes na ordem em que o guia os cita.

# 1. what a client sends: a local socket server prints the exact request bytes,
#    answers one GET with an ETag, and answers the conditional GET with 304.
# 2. chunked framing, built by hand: hex length, bytes, CRLF, then a zero chunk.
# 3. the SSE wire format, written out in full.
# 4. the WebSocket handshake answer and a masked text frame:
GUID = b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"          # RFC 6455
accept = base64.b64encode(hashlib.sha1(key + GUID).digest())
masked = bytes(b ^ mask[i % 4] for i, b in enumerate(payload))
frame = bytes([0x81, 0x80 | len(payload)]) + mask + masked   # FIN, text, masked
# 5. the same record as compact JSON, as a SOAP 1.2 envelope and as protobuf,
#    with gzip sizes; the protobuf message is built with a descriptor made at
#    run time, so the bytes come from the real implementation, and
#    Order.FromString(as_pb) == pb checks the round trip.
# 6. gRPC framing: struct.pack(">BI", 0, len(as_pb)) + as_pb
# 7. MQTT 3.1.1 CONNECT and a QoS 1 PUBLISH, with the remaining-length varint:
def remaining_length(n):
    out = bytearray()
    while True:
        d, n = n % 128, n // 128
        out.append(d | (0x80 if n else 0))
        if not n:
            return bytes(out)

Duas coisas que o script deliberadamente não faz: ele não mede vazão nem latência (um socket local não diria nada sobre uma rede real) e não implementa nenhum protocolo por completo. Ele produz os bytes que as especificações descrevem, para que os números deste guia possam ser conferidos em vez de acreditados.

Fontes

Pratique este tema: Networking & APIs

Mais guias