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ê quer | Leia |
|---|---|
| Uma decisão, hoje | A seção 1, depois a seção 13 (escolher), depois a família que você escolheu |
| Entender um protocolo | A seção dele; cada uma termina dizendo onde ele serve e onde não |
| Ler um protocolo que você nunca viu | As seis perguntas da seção 1, depois a seção 12 (as preocupações transversais) |
| O quadro completo | Em ordem. As seções 4 (SOAP), 5 (gRPC) e 10 (mensageria) são os aprofundamentos |
Que tipo de evidência há neste guia.
| Tipo | Onde | Quanto confiar |
|---|---|---|
| Texto de especificação | as RFCs e os documentos do W3C e da OASIS citados em cada seção e em Fontes | tanto quanto o documento; confira sempre qual versão do protocolo você tem |
| Bytes produzidos aqui | os hex dumps e os tamanhos das seções 2, 5, 6, 8 e 10 | foram produzidos pelo script do apêndice, em Python 3.13 e curl 8.5, e você pode executá-lo |
| Aritmética | as comparações de tamanho de mensagem e de idas e voltas | decorre dos tamanhos em bytes mostrados; nada é extrapolado para o seu tráfego |
| Medido em produção | nenhum | nenhum 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.
| # | Pergunta | Por que ela decide como é conviver com ele |
|---|---|---|
| 1 | Delimitaçã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 |
| 2 | Endereç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 |
| 3 | Quem 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 |
| 4 | Tipos: 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ã |
| 5 | Erros: 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" |
| 6 | Evoluçã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.
| Protocolo | Delimitação | Endereçamento | Quem fala | Esquema | Erros | Uso típico |
|---|---|---|---|---|---|---|
| HTTP/1.1 | Content-Length ou chunked | URL | o cliente pede, o servidor responde | nenhum embutido | código de status | tudo na web |
| HTTP/2 e /3 | frames binários por stream | URL | o cliente pede; muitos streams ao mesmo tempo | nenhum embutido | código de status mais erros de stream | o mesmo, mais rápido |
| REST sobre HTTP | a do HTTP | uma URL por recurso | o cliente | opcional (OpenAPI) | código de status mais um corpo | APIs web públicas e internas |
| SOAP | a do HTTP; o corpo é um envelope XML | um endpoint mais um nome de ação | o cliente | WSDL e XSD, obrigatórios | elemento Fault | integração corporativa, governo, legado |
| JSON-RPC 2.0 | a do HTTP, ou um fluxo de JSON | nome do método | o cliente, e notificações | nenhum embutido | objeto error numérico | ferramentas internas, nós de blockchain, editores |
| gRPC | prefixo de 5 bytes por mensagem dentro de frames HTTP/2 | /package.Service/Method | os dois, com streaming em qualquer direção | protobuf, compilado | status numérico nos trailers | serviço a serviço dentro de um sistema |
| GraphQL | a do HTTP; um POST | um endpoint, a consulta nomeia os dados | o cliente | esquema, com introspecção | array errors, normalmente com HTTP 200 | uma API alimentando muitas telas diferentes |
| WebSocket | o seu próprio cabeçalho de frame | a URL do upgrade | os dois, a qualquer momento | nenhum embutido | código de fechamento | chat, jogos, painéis ao vivo |
| SSE | linhas; uma linha em branco encerra um evento | uma URL | só o servidor empurra | nenhum | status HTTP na conexão | cotações, progresso, notificações |
| Webhook | a do HTTP, invertida | a sua URL no sistema deles | eles chamam você | o deles | o seu código de status | integrações entre empresas |
| AMQP 0-9-1 | frames binários | exchange mais chave de roteamento | broker no meio | nenhum | erros de canal e de conexão | filas de trabalho, integração corporativa |
| MQTT | cabeçalho fixo de 2 bytes ou mais | tópico | broker no meio | nenhum | códigos de motivo (MQTT 5) | IoT, celular, qualquer enlace ruim |
| SMTP | por linha; um . encerra os dados | caixa postal | o cliente empurra para um servidor | nenhum | códigos de resposta de três dígitos | e-mail, e nada mais hoje em dia |
| SFTP | pacotes binários em um canal SSH | caminho de arquivo | o cliente | nenhum | códigos de status | transferê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étodo | Seguro | Idempotente | Corpo | Significado típico |
|---|---|---|---|---|
| GET | sim | sim | sem semântica definida | ler |
| HEAD | sim | sim | não | ler só os cabeçalhos |
| OPTIONS | sim | sim | não | o que posso fazer aqui (e a pré-verificação de CORS) |
| PUT | não | sim | sim | substituir em um endereço conhecido |
| DELETE | não | sim | opcional | remover |
| POST | não | não | sim | qualquer outra coisa: criar, agir, enviar |
| PATCH | não | não por definição | sim | mudanç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ê.
| Classe | Significado para um cliente | Códigos que vale conhecer exatamente |
|---|---|---|
| 1xx | continue esperando, vem algo aí | 100 Continue, 101 Switching Protocols (o upgrade do WebSocket) |
| 2xx | funcionou | 200, 201 com Location, 202 aceito e não concluído, 204 sem corpo |
| 3xx | procure em outro lugar, ou você já tem | 301/308 permanente, 302/307 temporário, 304 não modificado |
| 4xx | a requisição está errada; não a repita sem mudanças | 400 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 |
| 5xx | o servidor falhou; uma nova tentativa pode funcionar | 500, 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.1 | HTTP/2 | HTTP/3 | |
|---|---|---|---|
| Formato na rede | texto, uma requisição por vez por conexão | frames binários, muitos streams por conexão | frames binários sobre QUIC |
| Transporte | TCP | TCP | UDP, com o QUIC fornecendo streams e TLS 1.3 |
| Compressão de cabeçalhos | nenhuma (repita tudo) | HPACK | QPACK |
| Bloqueio | uma resposta lenta bloqueia a conexão; navegadores abrem cerca de seis | os streams são independentes no HTTP, mas um segmento TCP perdido trava todos | um pacote perdido trava apenas o seu próprio stream |
| Server push | não | especificado, depois abandonado pelos navegadores | não |
| Trailers | trailers em chunked, raramente suportados | sim, e o gRPC depende deles | sim |
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:
- A ausência de estado é sobre o servidor, não sobre o cliente. Um cookie de sessão está bem; um servidor que guarda estado por cliente na memória e por isso não pode ser balanceado nem reiniciado, não (balanceamento de carga).
- HATEOAS é a restrição que ninguém implementa. O estilo de Fielding diz que as respostas deveriam levar links que conduzem o próximo passo. A maioria das APIs entrega documentação estática, e essa é a posição honesta da indústria: o nível mais alto do Modelo de Maturidade de Richardson é raro, e uma API que para abaixo dele continua útil.
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.
- O
Headeré o ponto de extensão. Tudo o que a família WS-* acrescenta (endereçamento, tokens de segurança, ids de transação, números de sequência de mensageria confiável) é um elemento de cabeçalho, não uma mudança no corpo. É por isso que a pilha pôde crescer sem novas versões do SOAP. mustUnderstand="true"significa: se você não implementa este cabeçalho, rejeite a mensagem inteira. É o mecanismo que impede um cabeçalho de segurança de ser ignorado em silêncio, e também o motivo de acrescentar um cabeçalho assim quebrar servidores antigos de propósito.- O corpo nomeia a operação. O endereçamento é "um endpoint mais um nome de operação", não uma URL por coisa, então caches e proxies HTTP não conseguem saber nada sobre uma chamada SOAP além do endpoint.
As duas versões diferem de formas que quebram clientes
| SOAP 1.1 (2000) | SOAP 1.2 (Recomendação do W3C, 2007) | |
|---|---|---|
| Namespace do envelope | http://schemas.xmlsoap.org/soap/envelope/ | http://www.w3.org/2003/05/soap-envelope |
| Tipo de conteúdo | text/xml | application/soap+xml |
| Qual operação | o cabeçalho HTTP SOAPAction separado, obrigatório | um parâmetro action no tipo de conteúdo (SOAPAction opcional) |
| Forma do fault | faultcode, faultstring, faultactor, detail | Code com Value e Subcode, Reason com idioma, Detail |
| Códigos de fault | Client, Server, VersionMismatch, MustUnderstand | Sender, 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ão | O que acrescenta | Onde você o vê |
|---|---|---|
| WS-Security | partes da própria mensagem assinadas e cifradas, com X.509 ou tokens de usuário, independentemente do transporte | bancos, governo, qualquer lugar em que a mensagem precise continuar assinada depois de sair do túnel TLS |
| WS-Addressing | ids de mensagem e endpoints de resposta e de falha em cabeçalhos | SOAP assíncrono, retornos de chamada, brokers no meio do caminho |
| WS-ReliableMessaging | nú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 ordem | integrações de telecomunicações e de ERP sobre enlaces instáveis |
| WS-Policy | declaraçõ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 / XOP | anexos binários enviados como bytes de verdade em vez de base64 dentro do XML | documentos, 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ódigo | Significado |
|---|---|
| −32700 | JSON inválido |
| −32600 | não é um objeto de requisição válido |
| −32601 | método não encontrado |
| −32602 | parâmetros inválidos |
| −32603 | erro interno |
| −32000 a −32099 | reservados 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ódigo | Nome | Repetir? |
|---|---|---|
| 0 | OK | — |
| 1 | CANCELLED | não, quem chamou desistiu |
| 3 | INVALID_ARGUMENT | não, corrija a requisição |
| 4 | DEADLINE_EXCEEDED | talvez, com um prazo maior |
| 5 | NOT_FOUND | não |
| 6 | ALREADY_EXISTS | não, e muitas vezes significa que a sua primeira tentativa funcionou |
| 7 | PERMISSION_DENIED | não |
| 8 | RESOURCE_EXHAUSTED | sim, com recuo |
| 9 | FAILED_PRECONDITION | não, até o estado mudar |
| 10 | ABORTED | sim, normalmente um conflito de concorrência |
| 12 | UNIMPLEMENTED | não |
| 13 | INTERNAL | não, é um defeito |
| 14 | UNAVAILABLE | sim, com recuo |
| 16 | UNAUTHENTICATED | nã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):
| Formato | Bytes | Com gzip |
|---|---|---|
| protobuf | 39 | 57 |
| JSON, compacto | 122 | 118 |
| envelope SOAP 1.2, XML | 406 | 258 |
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 fio | Usado para | Como é delimitado |
|---|---|---|
| 0 | int32, int64, uint*, bool, enum | varint |
| 1 | fixed64, double | 8 bytes |
| 2 | string, bytes, mensagens embutidas, campos repetidos empacotados | comprimento em varint, depois tantos bytes |
| 5 | fixed32, float | 4 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:
- Nunca reuse um número de campo. Marque campos removidos como
reserved; um número reusado faz dados antigos serem decodificados no campo errado, em silêncio. - Acrescentar um campo é seguro. Código antigo não conhece o número e o mantém como campo desconhecido (o proto3 preserva campos desconhecidos desde a versão 3.5, então um proxy não destrói dados que não entende).
- Renomear um campo é seguro na rede e quebra qualquer coisa que use o mapeamento JSON ou os acessadores gerados.
- Mudar um tipo normalmente não é seguro.
int32paraint64por acaso funciona para valores pequenos;int32parastringnão. - No proto3 todo escalar tem um valor padrão e não é enviado quando é igual ao padrão, então "ausente" e "zero" são a mesma coisa, a menos que você marque o campo como
optional(restaurado na 3.15) ou use uma mensagem de empacotamento.
Compare como cada formato responde à pergunta 6 da seção 1:
| Formato | Onde vive o esquema | Acrescentar um campo | Remover um | Pego por |
|---|---|---|---|---|
| JSON | em nenhum lugar, ou no OpenAPI ao lado | seguro, se os clientes ignoram extras | quebra quem o lia | testes, ou a produção |
| XML com XSD | o esquema, distribuído | exige mudança de esquema, muitas vezes um novo namespace | o mesmo | um validador, antes do seu código |
| protobuf | o .proto, compilado nos dois lados | seguro | seguro, se o número for reservado | o compilador, e uma verificação de registro de esquemas no CI |
| GraphQL | o esquema do servidor, com introspecção | seguro | @deprecated, depois acompanhe o uso | a 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 tradicional | application/graphql-response+json, o tipo que a especificação recomenda | |
|---|---|---|
| JSON malformado ou requisição ilegível | muitas vezes 400 | 400 |
| Um documento que falha na validação | em geral 200, com errors e sem data | 400 |
Um erro de campo, com data parcial | 200 | 200 |
| Método errado, ou um tipo de mídia que o servidor não aceita | 405, 415 | 405, 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:
| Campo | Valores |
|---|---|
| Opcodes | 0x0 continuação, 0x1 texto, 0x2 binário, 0x8 fechamento, 0x9 ping, 0xA pong |
| Mascaramento | obrigató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 |
| Comprimento | 0 a 125 embutido; 126 significa que vem um comprimento de 2 bytes; 127, de 8 bytes |
| Códigos de fechamento | 1000 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ões | permessage-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:
- Reconexão, com recuo e retomada. Redes caem; o protocolo não diz nada. Clientes precisam de uma repetição com jitter e de uma forma de dizer "eu tinha o evento 41" (padrões de resiliência).
- Correlação entre requisição e resposta. Se você quer uma resposta para uma mensagem, você inventa ids. É por isso que JSON-RPC sobre WebSocket é uma combinação tão comum.
- Batimentos. Balanceadores de carga e NATs descartam conexões ociosas, muitas vezes depois de 60 segundos. Frames de ping e pong as mantêm vivas e detectam uma conexão meio aberta.
- Contrapressão. Um consumidor lento faz o servidor acumular dados. Você precisa de uma fila limitada por conexão e de uma política de transbordo: descartar, agregar ou desconectar.
- Autenticação depois do upgrade. Navegadores não conseguem definir cabeçalhos no handshake de um WebSocket, então o token vai em um cookie, em um parâmetro de consulta (que acaba nos logs de acesso) ou em uma primeira mensagem depois de conectar. A última é a mais limpa.
- Escala horizontal. Conexões têm estado, então uma distribuição para muitos exige um barramento atrás dos servidores, e o balanceador precisa manter a conexão em um nó (balanceamento de carga).
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 polling | SSE | WebSocket | |
|---|---|---|---|
| Direção | servidor para cliente, uma mensagem por requisição | servidor para cliente, contínuo | nas duas direções |
| Transporte | HTTP puro | HTTP puro | upgrade de HTTP, depois frames |
| Carga | qualquer coisa | texto UTF-8 | texto ou binário |
| Reconectar e retomar | você escreve | embutido (Last-Event-ID) | você escreve |
| Problemas com proxy e firewall | quase nenhum | poucos (atenção ao buffer de resposta) | alguns (o upgrade precisa ser permitido, tempos limite de inatividade) |
| Custo por mensagem | uma requisição e uma resposta completas | alguns bytes | 2 a 6 bytes |
| Bom para | notificações raras | cotações, progresso, logs, feeds | chat, 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:
- 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.
- Rejeite carimbos de tempo antigos (uma janela de alguns minutos), ou uma requisição capturada pode ser repetida para sempre.
- 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.
- 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).
- Não presuma ordem. O
payment.succeededpode chegar antes doorder.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. - 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:
- Confirmações de publicação: sem elas, o
basic.publishé dispare-e-esqueça, e uma reinicialização do broker perde mensagens que você acredita enviadas. - Prefetch do consumidor (
basic.qos): o número de mensagens não confirmadas que um consumidor pode manter. Deixe sem limite e um consumidor pega a fila inteira; ponha em 1 e você paga uma ida e volta por mensagem. - Ack, nack e reject, com um sinalizador
requeue. Reenfileirar uma mensagem que sempre falha é como uma mensagem envenenada gira para sempre, então combine isso com um dead-letter exchange e uma contagem de reentregas. - TTLs de fila e de mensagem, e dead-letter exchanges: a única forma de evitar que uma fila travada cresça até o disco encher.
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:
| Recurso | O que faz | A pegadinha |
|---|---|---|
| QoS 0 | dispare e esqueça | perdida a qualquer soluço, e isso muitas vezes está bem para um sensor |
| QoS 1 | ao menos uma vez, com confirmação | duplicatas, então o receptor precisa ser idempotente |
| QoS 2 | exatamente uma vez, handshake de quatro etapas | o mais lento e com mais estado por mensagem; raramente vale a pena |
| Mensagem retida | o broker guarda a última mensagem por tópico e a dá a novos assinantes | não é histórico, só o valor mais recente, e persiste até ser substituído |
| Último desejo | o broker publica uma mensagem se um cliente desaparecer | a única forma de os outros saberem que um dispositivo ficou offline |
| Keep-alive | um intervalo de batimento acordado no CONNECT | uma regra de bolso é o cliente usar metade do intervalo no seu próprio timer |
| Sessão limpa / expiração de sessão | se assinaturas e mensagens enfileiradas sobrevivem a uma desconexão | uma 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:
- As portas significam coisas diferentes. A 25 é relay entre servidores e é bloqueada pela maioria das redes e dos provedores de nuvem para saída; a 587 é submissão autenticada (RFC 6409) com STARTTLS; a 465 é submissão sobre TLS implícito e volta a ser recomendada pela RFC 8314. Código que não consegue enviar e-mail de um host novo normalmente está apontado para a 25.
- 4xx é "tente mais tarde", 5xx é "nunca". Um remetente que trata 450 como permanente perde e-mails; um que repete 550 para sempre acaba bloqueado.
- Uma linha contendo apenas um ponto encerra a mensagem, então uma linha do corpo que começa com ponto precisa ser duplicada (dot-stuffing). Toda biblioteca de e-mail faz isso; remetentes caseiros são onde isso quebra.
- O remetente do envelope não é o cabeçalho
From:. Retornos vão para o endereço do envelope, e é essa divergência que o SPF verifica. - Entregabilidade é DNS, não SMTP. SPF, DKIM e DMARC são registros DNS mais um cabeçalho de assinatura; sem eles, uma conversa SMTP tecnicamente perfeita cai no spam.
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.
| FTPS | SFTP | SCP | |
|---|---|---|---|
| O que é | FTP com TLS (AUTH TLS, RFC 4217) | um subsistema de transferência de arquivos do SSH, na porta 22 | um comando de cópia, historicamente um protocolo próprio |
| Relação com o FTP | o mesmo protocolo, cifrado | não relacionado, apesar do nome | não relacionado |
| Portas | 21 mais uma faixa de dados | uma, a 22 | 22 |
| Amizade com firewalls | ruim (a faixa de dados) | boa | boa |
| Recursos | listagem de diretório, retomada | listagem, retomada, atributos, leituras e escritas parciais | só 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
| Protocolo | Sem TLS | Com TLS | Observação |
|---|---|---|---|
| HTTP | 80 | 443 | a 443 é a única porta com que você pode contar para atravessar uma rede corporativa |
| WebSocket | 80 (ws://) | 443 (wss://) | é HTTP até o 101 |
| gRPC | — | 443, ou qualquer porta internamente | é HTTP/2, então as mesmas portas do HTTP |
| SMTP | 25 relay, 587 submissão | 465 submissão, ou STARTTLS na 587 | a 25 de saída é bloqueada em quase todo lugar |
| IMAP / POP3 | 143 / 110 | 993 / 995 | |
| FTP | 21 mais dados | 21 com AUTH TLS (FTPS) | o problema é o canal de dados, não a porta |
| SSH, SFTP | 22 | 22 (o SSH é sempre cifrado) | uma porta para shell, transferência e encaminhamento |
| AMQP 0-9-1 | 5672 | 5671 | a interface de gestão do RabbitMQ é a 15672, outra coisa |
| MQTT | 1883 | 8883 | MQTT sobre WebSocket usa as portas web, ou uma que o broker escolha |
| DNS | 53 | 853 (DoT), 443 (DoH) | veja o guia de DNS |
Autenticação, por protocolo
| Protocolo | Mecanismos usuais | A aresta afiada |
|---|---|---|
| HTTP, REST, GraphQL | Authorization: Bearer (RFC 6750), Basic (RFC 7617), cookies, chaves de API, TLS mútuo | um token em um parâmetro de consulta acaba em logs, caches e cabeçalhos Referer |
| gRPC | cabeçalhos de metadados (authorization), ou TLS mútuo com credenciais por canal | os 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 |
| SOAP | cabeçalhos WS-Security (token de usuário, assinatura X.509), ou HTTP Basic com TLS | assinaturas no nível da mensagem sobrevivem a brokers e arquivos; autenticação de transporte não |
| WebSocket | cookie no handshake, token na primeira mensagem, ou um tíquete de curta duração na URL | navegadores não conseguem definir cabeçalhos no handshake, então o desenho é forçado |
| AMQP, MQTT | usuário e senha na conexão, certificados de cliente, ACLs do broker por fila ou tópico | a autorização é do broker, não da aplicação: acerte os padrões de tópico ou de fila |
| SMTP | SASL na porta de submissão | a autenticação diz quem pode enviar, não qual endereço pode alegar |
| SSH, SFTP | chave 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ção | HTTP / REST | gRPC | GraphQL | JSON-RPC | SOAP | MQTT 5 |
|---|---|---|---|---|---|---|
| Requisição malformada | 400 | 3 INVALID_ARGUMENT | 400, ou 200 com errors e sem data (seção 7) | −32600 / −32602 | fault Sender | código de motivo 0x81 |
| Não autenticado | 401 | 16 UNAUTHENTICATED | 200 com um erro de autenticação | próprio | fault de segurança | 0x87 na conexão |
| Autenticado, sem permissão | 403 | 7 PERMISSION_DENIED | errors com um caminho e campo nulo | próprio | fault Sender | 0x87 na publicação |
| A coisa não existe | 404 | 5 NOT_FOUND | null mais um erro | próprio | fault de aplicação | — |
| Conflito com o estado atual | 409 / 412 | 10 ABORTED, 9 FAILED_PRECONDITION | errors | próprio | fault de aplicação | — |
| Requisições em excesso | 429 com Retry-After | 8 RESOURCE_EXHAUSTED | errors | próprio | 0x97 cota excedida | — |
| O servidor quebrou | 500 | 13 INTERNAL | errors | −32603 | fault Receiver | — |
| Temporariamente fora | 503 com Retry-After | 14 UNAVAILABLE | errors | −32603 | fault Receiver | conexão fechada |
| Demorou demais | 504 | 4 DEADLINE_EXCEEDED | errors | tempo limite | tempo limite | tempo 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
| Protocolo | Como uma versão é expressa | Mudança aditiva | Mudança incompatível |
|---|---|---|---|
| REST | caminho (/v2/orders), tipo de mídia (application/vnd.shop.v2+json) ou um cabeçalho | acrescente um campo, ignore os desconhecidos | uma nova versão, as duas servidas por um tempo |
| GraphQL | normalmente nenhuma: um esquema em evolução | acrescente campos e tipos | @deprecated, meça o uso, depois remova |
| gRPC, protobuf | o nome do pacote (shop.v2) | acrescente um campo com um número novo | um novo serviço ou pacote; nunca reuse um número de campo |
| SOAP | um novo namespace de destino e uma nova URL de WSDL | um novo elemento opcional, se o esquema permitir | um novo namespace; o antigo continua rodando |
| JSON-RPC | o nome do método (orders.get.v2) | acrescente um parâmetro opcional | um novo nome de método |
| MQTT, AMQP | o tópico ou a chave de roteamento, e um campo de versão na carga | um campo novo, se o consumidor tolerar | um 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
| Protocolo | Para onde ele vai |
|---|---|
| HTTP, REST, GraphQL | o cabeçalho traceparent |
| gRPC | metadados, que são cabeçalhos HTTP/2, então o mesmo nome |
| AMQP | um cabeçalho de mensagem ou propriedade de aplicação |
| MQTT 5 | uma propriedade de usuário; no 3.1.1 não há lugar além da carga |
| SOAP | um elemento de cabeçalho, normalmente o MessageID do WS-Addressing |
| Webhooks | um 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.
| Protocolo | Acompanhe |
|---|---|
| HTTP, REST | taxa 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 |
| GraphQL | a 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 |
| gRPC | contagens 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, SSE | conexõ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, MQTT | profundidade de fila e atraso do consumidor, contagens de reentrega, mensagens em dead-letter e memória do broker |
| SMTP | aceitos 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ção | Use | O que você aceita |
|---|---|---|
| Uma API pública ou voltada a parceiros | REST sobre HTTP com JSON | nenhuma 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 linguagens | gRPC | uma etapa de build, um registro de esquemas e proxies que precisam lidar com trailers de HTTP/2 |
| Um backend, vários front ends muito diferentes | GraphQL | cache, controle de custo e autorização passam a ser o seu código |
| Um banco, uma seguradora, um órgão de governo do outro lado | SOAP | verbosidade, e 5xx em erros de negócio |
| Atualizações ao vivo para um navegador | SSE, e WebSocket se você precisar enviar para cima | conexões de longa duração para operar e escalar |
| Outra empresa precisa lhe contar sobre eventos | webhooks | verificação de assinatura, repetições, duplicatas e nenhuma ordem |
| Trabalho que não pode ser perdido e pode ser lento | AMQP ou um log | um broker para operar, e profundidade de fila para acompanhar |
| Dispositivos a bateria ou em enlace tarifado | MQTT | nenhum esquema, e o desenho de tópicos como fronteira de segurança |
| Arquivos entre empresas | SFTP | gestão de chaves, e uma transferência que não é uma transação |
| SMTP, por um provedor | entregabilidade é 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:
- HTTP e JSON até algo doer. É a única opção que todo cliente, proxy, log, ferramenta de teste e pessoa recém-contratada já entende. Abra mão disso por um motivo medido, não por preferência.
- Dois protocolos são uma resposta normal. Um sistema típico é REST na borda, gRPC ou uma fila por dentro, SSE para atualizações ao vivo e SFTP porque um parceiro insiste. O erro não é ter vários; é ter vários que dizem a mesma coisa de formas diferentes.
- Trocar de protocolo raramente corrige latência. Uma troca de protocolo compra bytes e idas e voltas; uma cascata de cinco chamadas dependentes custa cinco vezes a latência em qualquer protocolo. Conte as idas e voltas primeiro (DNS, HTTP/2 e cascatas).
Migrar sem reescrever
| De | Para | O caminho habitual |
|---|---|---|
| SOAP | REST ou gRPC | mantenha 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 |
| REST | gRPC internamente | introduza-o em um par de serviços conversadeiro, mantenha REST na borda; um gateway pode traduzir (grpc-gateway, Envoy) |
| Consultas REST periódicas | SSE ou WebSocket | entregue 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 parceiro | webhooks | aceite webhooks como um empurrãozinho e mantenha o trabalho de consulta em baixa frequência como rede de segurança |
| Uma fila usada como RPC | gRPC ou HTTP | se quem chama espera a resposta, nunca foi mensageria |
14. Erros comuns
- Tratar o HTTP 500 de um fault SOAP como "o servidor está quebrado" no monitoramento, e acordar alguém por um erro de negócio.
- Enviar um envelope SOAP 1.2 (ou nenhum
SOAPAction) a um endpoint SOAP 1.1 e concluir que o serviço está fora. - Repetir um POST ou um PATCH depois de um tempo limite sem uma chave de idempotência.
- Tratar o PATCH como idempotente porque os seus próprios patches por acaso são, e esperar que um proxy ou uma camada de repetição saiba disso.
- Usar 200 para tudo, ou 500 para erros do cliente, e fazer cada cliente interpretar o corpo.
- Devolver erros de GraphQL e alertar apenas com base em códigos de status HTTP, de modo que uma API meio quebrada parece perfeita.
- Deixar um cliente GraphQL enviar qualquer consulta em produção: sem limite de profundidade, sem orçamento de custo, sem consultas persistidas.
- Esperar que uma CDN guarde um POST em cache, seja GraphQL ou um endpoint de RPC.
- Reusar um número de campo do protobuf, ou remover um campo sem reservá-lo.
- Supor comportamento de
optionalem escalares do proto3: um zero e um valor ausente são a mesma coisa, a menos que você tenha pedido presença. - Colocar um serviço gRPC atrás de um proxy que descarta trailers de HTTP/2 e depois depurar "a chamada nunca termina".
- Balancear gRPC com um balanceador TCP, de modo que um backend recebe todas as chamadas de cada canal.
- Abrir um WebSocket quando o tráfego é de uma direção, e herdar reconexão, batimentos e roteamento fixo por nada.
- Esquecer os batimentos e depois culpar a rede por conexões que morrem depois de exatamente 60 segundos.
- Interpretar o corpo de um webhook antes de verificar a assinatura, ou verificar uma cópia reserializada dele.
- Processar um webhook de forma síncrona, estourar o tempo limite do remetente e receber o mesmo evento outras cinco vezes.
- Supor que eventos de webhook chegam em ordem, ou exatamente uma vez.
- Escolher o QoS 2 do MQTT por padrão, ou tratar uma mensagem retida como histórico.
- Assinar
#em um broker multi-inquilino. - Dizer "usamos AMQP" sem dizer 0-9-1 ou 1.0.
- Enviar e-mail pela porta 25 em um host na nuvem, ou tratar uma resposta SMTP 4xx como permanente.
- Rodar FTP em modo ativo atravessando um NAT, ou pensar que SFTP é FTP com TLS.
- Aceitar uma chave de host SSH alterada porque foi mais rápido que perguntar por quê.
- Citar uma tabela de tamanhos de mensagem (inclusive a deste guia) como se ela previsse a sua latência.
15. O que mencionar em uma entrevista
- "Um protocolo são seis decisões: delimitação, endereçamento, quem fala primeiro, esquema, erros e evolução. A maioria das discussões sobre protocolo é, no fundo, uma dessas seis disfarçada."
- Seguro e idempotente são as duas palavras que importam no HTTP: elas decidem o que um rastreador pode buscar e o que uma nova tentativa pode repetir. GET, HEAD, PUT e DELETE são idempotentes e o POST não é; o PATCH não é idempotente como método, embora um documento de patch específico possa ser, e é essa distinção que os entrevistadores estão esperando ouvir.
- 401 é "não sei quem você é", 403 é "sei quem você é e não", 429 e 503 são convites a voltar, e 500 não é.
- Uma requisição condicional com
ETageIf-None-Matchtransforma uma leitura repetida em uma 304 sem corpo; oIf-Matchem uma escrita dá concorrência otimista com um 412. - O valor do SOAP é o contrato e a segurança no nível da mensagem (WS-Security), não o XML; a sua esquisitice é que os faults chegam como HTTP 500.
- O gRPC é protobuf mais HTTP/2: prefixos de comprimento de cinco bytes, metadados como cabeçalhos, o status nos trailers, prazos propagados com a chamada. Navegadores precisam do gRPC-Web, e um canal é uma conexão, razão pela qual o balanceamento exige L7.
- O formato de fio do protobuf leva números de campo, não nomes, e é por isso que acrescentar um campo é seguro, reusar um número é perigoso e renomear é grátis na rede, mas quebra o mapeamento JSON.
- Um erro de campo do GraphQL volta como 200 com um array
errors, então o monitoramento por status não o percebe; um erro de requisição pode ser um 400, dependendo do tipo de mídia e do rascunho que o servidor segue. O GraphQL também perde o cache de CDN, e precisa de limites de profundidade e de custo, de agrupamento para o N+1 e de consultas persistidas. - O SSE é um fluxo de texto em uma direção com reconexão embutida e
Last-Event-ID; o WebSocket são frames nas duas direções depois de um upgrade 101, com mascaramento no cliente e nenhuma reconexão, correlação ou contrapressão próprias. - Webhooks: verifique o HMAC sobre o corpo bruto, rejeite carimbos de tempo antigos, responda 2xx rápido, elimine duplicatas pelo id do evento e nunca presuma ordem.
- O MQTT é para enlaces ruins: uma publicação de 22 bytes contra um POST HTTP de 103, QoS 0/1/2, mensagens retidas, últimos desejos e tópicos como fronteira de segurança. AMQP 0-9-1 e AMQP 1.0 são protocolos diferentes.
- "Use SFTP" é a resposta inteira para transferência de arquivos; o SFTP é SSH, não FTP, e precisa de uma porta.
- E a resposta de julgamento: HTTP com JSON até algo doer; troque de protocolo por um motivo medido, e espere rodar dois por um tempo.
Resumo rápido
- Todo protocolo responde a seis perguntas: delimitação, endereçamento, quem fala primeiro, esquema, erros, evolução.
- O vocabulário do HTTP (métodos, códigos de status, requisições condicionais,
Vary) é o que faz caches, proxies e novas tentativas funcionarem; o REST é usá-lo de propósito. Seguro e idempotente são propriedades do método, com exceção do PATCH, em que o documento de patch decide. - O SOAP compra um contrato compilado e segurança no nível da mensagem ao preço da verbosidade e de faults em HTTP 500; chamá-lo é um dia de trabalho, não um trimestre.
- O gRPC é protobuf sobre HTTP/2, com mensagens com prefixo de comprimento, status nos trailers e prazos no protocolo; serve para tráfego interno, de alta taxa e em várias linguagens.
- O protobuf leva números, não nomes: acrescente à vontade, nunca reuse um número e conte com uma etapa de build.
- O GraphQL move a escolha dos campos para o cliente e o custo de cache, autorização e limites de consulta para você; um campo que falha é um 200 com
errors, enquanto um documento rejeitado pode ser um 400. - SSE para empurrar em uma direção, WebSocket quando você precisa das duas, long polling quando a rede é hostil.
- Webhooks precisam de assinaturas, janelas contra repetição, confirmações rápidas, eliminação de duplicatas e nenhuma suposição sobre ordem.
- AMQP para filas de trabalho, MQTT para dispositivos em enlaces ruins, um log quando você precisa de reprodução; todos trocam acoplamento por um broker para operar.
- As portas do SMTP e a distinção entre 4xx e 5xx, a conexão de dados do FTP e o fato de o SFTP ser SSH são os três fatos legados que continuam custando dias às pessoas.
- Meça antes de trocar: uma troca de protocolo compra bytes e idas e voltas, não uma arquitetura diferente.
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
- IETF, HTTP: RFC 9110, semântica, RFC 9111, cache, RFC 9112, HTTP/1.1, RFC 9113, HTTP/2, RFC 9114, HTTP/3 e RFC 5789, PATCH.
- IETF, RFC 9457: Problem Details for HTTP APIs (que torna obsoleta a RFC 7807).
- IETF, RFC 6455: The WebSocket Protocol, RFC 7692, permessage-deflate e RFC 8441: Bootstrapping WebSockets with HTTP/2.
- WHATWG, Server-sent events, no padrão HTML.
- W3C, SOAP 1.2 Part 1: Messaging Framework, SOAP 1.1 e WSDL 1.1.
- OASIS, WS-Security 1.1.1 e MQTT 5.0; MQTT 3.1.1.
- Grupo de trabalho do JSON-RPC, especificação do JSON-RPC 2.0.
- Autores do gRPC, gRPC over HTTP/2, códigos de status e prazos.
- Google, Protocol Buffers: encoding e guia da linguagem proto3.
- GraphQL Foundation, a especificação do GraphQL e serving over HTTP.
- AMQP: especificação do AMQP 0-9-1 e o modelo do RabbitMQ; OASIS, AMQP 1.0.
- IETF, e-mail e transferência: RFC 5321, SMTP, RFC 6409, submissão, RFC 8314, TLS para submissão e acesso, RFC 9051, IMAP4rev2, RFC 959, FTP, RFC 4217, FTP sobre TLS e RFC 4251, arquitetura do SSH.
- W3C, Trace Context (o cabeçalho
traceparent). - Roy T. Fielding, Architectural Styles and the Design of Network-based Software Architectures, capítulo 5 (REST).
- MDN Web Docs, HTTP e a API de WebSockets.
Pratique este tema: Networking & APIs