CS Fundamentals Trainer · Guides
Protocols: HTTP, SOAP, REST, gRPC, GraphQL, WebSockets and messaging
The protocols a working engineer meets, compared with the same six questions: HTTP and REST, SOAP and the WS-* family, JSON-RPC and gRPC with protobuf on the wire, GraphQL, WebSockets, server-sent events and long polling, webhooks, AMQP, MQTT and STOMP, and SMTP, FTP, SFTP and SSH, with real bytes, an error-vocabulary table across protocols, ports, versioning, tracing and a decision chart.
66 min read
"Which protocol should this use?" is usually answered by habit: HTTP and JSON, because that is what the last service used. Habit is not a bad default, but it hides the question. A protocol decides how two programs find each other, how a message is framed, who may speak first, what counts as an error, and what happens when one side is upgraded and the other is not. Those decisions are what make a protocol cheap or expensive to live with, long after the first version ships.
This guide covers the protocols a working engineer actually meets: HTTP as the substrate, REST and SOAP on top of it, JSON-RPC and gRPC, GraphQL, WebSockets and server-sent events, webhooks, the messaging protocols (AMQP, MQTT, STOMP), and the older ones that refuse to die (SMTP, FTP, SFTP, SSH). It compares them with the same six questions throughout, and it shows the actual bytes wherever bytes make the point.
How to read it.
| You want | Read |
|---|---|
| A decision, today | Section 1, then section 13 (choosing), then the family you picked |
| To understand one protocol | Its own section; each ends with where it fits and where it does not |
| To read a protocol you have never seen | Section 1's six questions, then section 12 (the cross-cutting concerns) |
| The whole picture | In order. Sections 4 (SOAP), 5 (gRPC) and 10 (messaging) are the deep dives |
What kind of evidence is in this guide.
| Kind | Where | How far to trust it |
|---|---|---|
| Specification text | the RFCs, W3C and OASIS documents named in each section and in Sources | as far as the document; always check which version of the protocol you have |
| Bytes produced here | the hex dumps and sizes in sections 2, 5, 6, 8 and 10 | they were produced by the script in the appendix, on Python 3.13 and curl 8.5, and you can run it |
| Arithmetic | the message-size and round-trip comparisons | it follows from the byte counts shown; nothing is extrapolated to your traffic |
| Measured in production | none | no latency or throughput figure here describes a real system. Section 12 says what to measure instead |
Transport and infrastructure are covered by their own guides, and this one does not repeat them: TCP in practice, DNS, HTTP/2, HTTP/3 and CDNs, TLS and HTTPS, load balancing and what happens when you type a URL.
1. Six questions every protocol answers
In short. Every protocol on this page answers the same six questions. Learn the questions and a protocol you have never seen becomes readable in an afternoon.
| # | Question | Why it decides how you live with it |
|---|---|---|
| 1 | Framing: where does one message end? | A length prefix, a terminator, or "until the connection closes". This decides whether streaming is possible and whether a parser can be attacked with a mismatched length |
| 2 | Addressing: how is a thing named? | A URL path, a method name, a topic, a queue, a mailbox. It decides what a cache, a proxy or an access rule can reason about |
| 3 | Who speaks first, and how often? | Request/response, one-way push, or either side at any time. It decides how firewalls, load balancers and timeouts behave |
| 4 | Types: is there a schema, and who holds it? | None (JSON), a document (WSDL, OpenAPI), or a compiled contract (protobuf). It decides whether a breaking change is caught at build time or at 3 a.m. |
| 5 | Errors: how is failure expressed? | A status code, a fault document, an error array, a reason code. It decides whether a retry is safe, and whether a client can tell "no" from "not now" |
| 6 | Evolution: how do you add a field? | Additive by rule, by a new version in the URL, by a new namespace, or not at all. It decides how often you break somebody |
Use the questions as a checklist. The table below is the whole guide in one screen; the rest of it fills in the detail.
| Protocol | Framing | Addressing | Who speaks | Schema | Errors | Typical use |
|---|---|---|---|---|---|---|
| HTTP/1.1 | Content-Length or chunked | URL | client asks, server answers | none built in | status code | everything on the web |
| HTTP/2 and /3 | binary frames per stream | URL | client asks; many streams at once | none built in | status code plus stream errors | the same, faster |
| REST over HTTP | HTTP's | URL per resource | client | optional (OpenAPI) | status code plus a body | public and internal web APIs |
| SOAP | HTTP's, body is one XML envelope | one endpoint plus an action name | client | WSDL and XSD, mandatory | Fault element | enterprise, government, legacy integration |
| JSON-RPC 2.0 | HTTP's, or a stream of JSON | method name | client, and notifications | none built in | numeric error object | internal tools, blockchain nodes, editors |
| gRPC | 5-byte prefix per message inside HTTP/2 frames | /package.Service/Method | both, streaming either way | protobuf, compiled | numeric status in trailers | service-to-service inside one system |
| GraphQL | HTTP's; one POST | one endpoint, the query names the data | client | schema, introspectable | errors array, usually with HTTP 200 | one API feeding many different screens |
| WebSocket | its own frame header | the URL of the upgrade | both, at any time | none built in | close code | chat, games, live dashboards |
| SSE | lines, blank line ends an event | a URL | server pushes only | none | HTTP status at connect | tickers, progress, notifications |
| Webhook | HTTP's, inverted | your URL at their system | they call you | theirs | your status code | integrations between companies |
| AMQP 0-9-1 | binary frames | exchange plus routing key | broker in the middle | none | channel and connection errors | work queues, enterprise integration |
| MQTT | 2 or more byte fixed header | topic | broker in the middle | none | reason codes (MQTT 5) | IoT, mobile, anything on a bad link |
| SMTP | line-based, . ends the data | mailbox | client pushes to a server | none | three-digit reply codes | mail, and nothing else any more |
| SFTP | binary packets over an SSH channel | file path | client | none | status codes | file transfer between machines |
2. HTTP: the substrate almost everything sits on
In short. HTTP is a request/response protocol with a text-like surface, a huge amount of agreed semantics, and an infrastructure of caches and proxies that only works if you use its vocabulary correctly.
HTTP is specified in pieces: the semantics (methods, status codes, headers) in RFC 9110, the HTTP/1.1 syntax in RFC 9112, caching in RFC 9111, HTTP/2 in RFC 9113 and HTTP/3 in RFC 9114. The pieces matter because "HTTP" means two different things in a sentence: the meaning of a request, which is the same in every version, and the way bytes are written, which is not.
What a client really sends
Here is what curl put on the wire for one GET against a local server, as the server read it:
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
Four lines and a blank line. Three things are worth noting. Host is mandatory in HTTP/1.1, which is what makes virtual hosting possible: one address, many sites. The empty line is the framing: headers end there, and whatever follows is the body. And Accept is a wish, not a command; the server chooses.
The answer carried its own framing and its cache rules:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 27
ETag: "v3"
Cache-Control: max-age=60
{"id":"ord_7","total":4299}
The second request repeated the GET with If-None-Match: "v3", and the server answered without the body:
HTTP/1.1 304 Not Modified\r\n
ETag: "v3"\r\n
Cache-Control: max-age=60\r\n
\r\n
The 200 answer was 131 bytes of headers and body; the 304 was 68 bytes and no body. That is the whole idea of a conditional request: the server proves the client's copy is still good instead of sending it again. On a 2 MB response the saving is not 63 bytes, it is 2 MB, and it costs one header.
Framing without a length
When the server does not know the size in advance it can frame with chunks instead:
a\r\n
{"page":1}\r\n
a\r\n
{"page":2}\r\n
0\r\n
\r\n
Each chunk is a hex length, the bytes, then a zero-length chunk to end. Twenty bytes of payload cost 35 on the wire here, which is the price of being able to start sending before you know the total. This is how HTTP/1.1 streams, and it is why a proxy that buffers whole responses ruins streaming APIs. HTTP/2 and HTTP/3 do not use chunked encoding: they have their own frames, and Transfer-Encoding: chunked is not allowed there.
The method table, with the only two words that matter
| Method | Safe | Idempotent | Body | Typical meaning |
|---|---|---|---|---|
| GET | yes | yes | no defined semantics | read |
| HEAD | yes | yes | no | read the headers only |
| OPTIONS | yes | yes | no | what may I do here (and CORS preflight) |
| PUT | no | yes | yes | replace at a known address |
| DELETE | no | yes | optional | remove |
| POST | no | no | yes | anything else: create, act, submit |
| PATCH | no | not by definition | yes | partial change (RFC 5789) |
Safe means the request is not meant to change anything, so a crawler or a prefetch may issue it. Idempotent means doing it twice has the same effect as doing it once, which is exactly the property a retry needs. A proxy, a mobile network or your own retry policy will repeat requests, and POST is the method where that can double a charge, which is why idempotency keys exist (idempotency and exactly-once effects).
PATCH needs a sentence of its own, because the common shorthand "POST and PATCH are not idempotent" mixes up two different things. The method is not defined as idempotent: RFC 5789 says PATCH is neither safe nor idempotent, so a proxy, a gateway or a generic retry layer must not assume that repeating it is harmless. Whether a particular patch is idempotent depends on what the patch document says. {"op": "replace", "path": "/qty", "value": 5} lands on the same state however often it is applied; {"op": "increment", "path": "/qty", "by": 1} does not. So: the method gives you no guarantee, your patches may well have one, and the only way a client learns which is from your documentation or from an idempotency key you accept.
Content in a GET is a different kind of trap. Message framing does not forbid it, but RFC 9110 states that content received in a GET has no generally defined semantics: it cannot alter the meaning or the target of the request, caches and proxies key on the method and the URL alone, and it has enough history as a request-smuggling vector that some servers and intermediaries reject such a request outright. "Servers ignore it" is the usual outcome rather than a rule you can rely on, which is reason enough to keep a query in the URL, or to use POST and accept the loss of caching.
Status codes, read as a protocol
The class is the part a client should branch on, and the specific code is the part a human reads.
| Class | Meaning for a client | Codes worth knowing exactly |
|---|---|---|
| 1xx | keep waiting, something is coming | 100 Continue, 101 Switching Protocols (the WebSocket upgrade) |
| 2xx | it worked | 200, 201 with Location, 202 accepted and not finished, 204 no body |
| 3xx | look elsewhere, or you already have it | 301/308 permanent, 302/307 temporary, 304 not modified |
| 4xx | the request is wrong; do not retry it unchanged | 400 malformed, 401 not authenticated, 403 authenticated and not allowed, 404, 409 conflict, 412 precondition failed, 422 understood but semantically wrong, 429 too many requests |
| 5xx | the server failed; a retry may work | 500, 502 bad gateway, 503 unavailable (with Retry-After), 504 gateway timeout |
Two distinctions carry most of the value. 401 against 403: the first says "I do not know who you are", the second says "I know, and no". 429 and 503 against 500: the first two are invitations to come back, ideally with Retry-After; a bare 500 is not, and retrying it hard is how a wobble becomes an outage (resilience patterns).
For the body of an error, RFC 9457 defines application/problem+json, which replaced 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
}
type is a stable identifier a client can switch on, title and detail are for people, and extra members are allowed. Using it costs nothing and saves every client from parsing your prose.
Content negotiation, and the header that makes caching correct
A client states preferences (Accept, Accept-Encoding, Accept-Language), the server picks one and must then say what the answer depended on:
Vary: Accept-Encoding, Accept-Language
Without Vary, a shared cache can hand a German gzip answer to an English client asking for plain text. With too much Vary (User-Agent, for example) the cache hit rate collapses. Caching itself is covered in DNS, HTTP/2, HTTP/3 and CDNs.
The versions, in one table
| HTTP/1.1 | HTTP/2 | HTTP/3 | |
|---|---|---|---|
| Wire format | text, one request at a time per connection | binary frames, many streams per connection | binary frames over QUIC |
| Transport | TCP | TCP | UDP, with QUIC providing streams and TLS 1.3 |
| Header compression | none (repeat everything) | HPACK | QPACK |
| Blocking | one slow response blocks the connection; browsers open about six | streams are independent in HTTP, but a lost TCP segment stalls them all | a lost packet stalls only its own stream |
| Server push | no | specified, then abandoned by browsers | no |
| Trailers | chunked trailers, rarely supported | yes, and gRPC depends on them | yes |
What this means in practice: HTTP/1.1 rewards few, large requests and cache-friendly URLs; HTTP/2 and HTTP/3 make many small requests reasonable, which changes API design (the request-waterfall problem). Nothing above changes the meaning of a GET.
Where HTTP fits, and where it does not
It fits anything a client initiates, anything that benefits from caches, proxies and existing tooling, and anything that must cross a strange network: port 443 is the one port that always works. It does not fit server-initiated messages (sections 8 and 9), very chatty internal calls where the header overhead dominates (section 5), or a device on a metered radio link sending four bytes (section 10).
3. REST: HTTP used on purpose
In short. REST is not "JSON over HTTP". It is a set of constraints whose practical payoff is that generic infrastructure understands your API: caches, proxies, retries and conditional requests all work because the meaning lives in the method and the URL.
Roy Fielding described REST in 2000 as an architectural style with constraints: a uniform interface, statelessness, a client/server split, cacheability, layering, and code on demand. The part that earns its keep daily is the uniform interface. When "read order 7" is GET /orders/7, a CDN can cache it, a proxy can retry it, a browser can bookmark it and a log line tells you what happened. When it is POST /api with {"op":"getOrder","id":7}, none of that works, and you have an RPC API wearing REST's clothes.
A compact example of the vocabulary in use:
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
Two patterns in there are worth copying. If-Match on a write is optimistic concurrency: the write fails with 412 instead of silently overwriting a change made in the meantime. And the collection URL carries filters as query parameters, so the same resource can be cached per filter.
The design questions that follow (resource modelling, pagination, filtering, versioning, partial responses, bulk operations) are the subject of their own guide: designing a REST API. Two points belong here because they are protocol points, not design taste:
- Statelessness is about the server, not the client. A session cookie is fine; a server that keeps per-client state in memory and therefore cannot be load balanced or restarted is not (load balancing).
- HATEOAS is the constraint nobody implements. Fielding's style says responses should carry links that drive the next step. Most APIs ship static documentation instead, and that is the honest industry position: the Richardson Maturity Model's top level is rare, and an API that stops below it is still useful.
Where REST fits, and where it does not
It fits public APIs, anything a browser touches, anything with a long tail of unknown clients, and anything that benefits from caching. It struggles when one screen needs twelve resources (section 7 answers that), when the calls are internal and extremely frequent (section 5), and when the interaction is genuinely an action rather than a thing: POST /transfers is a resource, but "cancel this job if it has not started" is a verb, and dressing verbs as resources is where REST designs get silly.
4. SOAP and the WS-* family
In short. SOAP is an XML envelope with a mandatory machine-readable contract (WSDL) and a stack of optional standards for security, addressing and reliability. It is verbose and old, it is still everywhere in banking, insurance, telecoms, healthcare and government, and the reason is the contract, not nostalgia.
A SOAP message is one XML document with a fixed shape: an Envelope containing an optional Header and a mandatory Body.
<?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>
Three details in there explain most SOAP behaviour.
- The
Headeris the extension point. Everything WS-* adds (addressing, security tokens, transaction ids, reliable-messaging sequence numbers) is a header element, not a change to the body. This is why the stack could grow without new versions of SOAP. mustUnderstand="true"means: if you do not implement this header, reject the whole message. It is the mechanism that keeps a security header from being silently ignored, and it is also why adding a header can break old servers on purpose.- The body names the operation. Addressing is "one endpoint plus an operation name", not one URL per thing, so HTTP caches and proxies can tell nothing about a SOAP call beyond the endpoint.
The two versions differ in ways that break clients
| SOAP 1.1 (2000) | SOAP 1.2 (W3C Recommendation, 2007) | |
|---|---|---|
| Envelope namespace | http://schemas.xmlsoap.org/soap/envelope/ | http://www.w3.org/2003/05/soap-envelope |
| Content type | text/xml | application/soap+xml |
| Which operation | the separate SOAPAction HTTP header, mandatory | an action parameter on the content type (SOAPAction optional) |
| Fault shape | faultcode, faultstring, faultactor, detail | Code with Value and Subcode, Reason with language, Detail |
| Fault codes | Client, Server, VersionMismatch, MustUnderstand | Sender, Receiver, VersionMismatch, MustUnderstand, DataEncodingUnknown |
Plenty of production endpoints are still 1.1. If a client sends a 1.2 envelope to a 1.1 service, the usual answer is a VersionMismatch fault, and a missing SOAPAction against 1.1 often produces a bare HTTP error instead of a fault, which is the classic "it works in SoapUI but not from my code" situation.
A fault, in 1.2, and the status code that carries it:
<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>
Over the HTTP binding a fault arrives with HTTP 500 (a sender fault in SOAP 1.2 may use 400), which is the single most confusing thing about SOAP for people coming from REST: a perfectly well-handled business error ("no such order") is an HTTP 500. Monitoring that counts 5xx as "server broken" will scream at a SOAP service forever unless it parses the envelope.
WSDL: the contract that is the reason SOAP survives
A WSDL 1.1 document describes the service in five parts: types (XML Schema for every message), message, portType (the operations), binding (how they travel: SOAP over HTTP, document/literal) and service (the endpoint URL). It is machine-readable in a way OpenAPI only approximates, because the payload schema is XSD: types, cardinality, enumerations, patterns, nested structures, all validated by the stack before your code runs.
The practical consequence is tooling. Point a generator at a URL and get typed client code:
# .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)
That is the trade SOAP makes: a lot of ceremony, and in exchange a contract both sides can compile against, with a version mismatch caught by a schema validator rather than by a null in production.
The WS-* standards you may actually meet
| Standard | What it adds | Where you see it |
|---|---|---|
| WS-Security | signed and encrypted parts of the message itself, with X.509 or username tokens, independent of the transport | banking, government, anything where the message must stay signed after it leaves the TLS tunnel |
| WS-Addressing | message ids, reply-to and fault-to endpoints in headers | asynchronous SOAP, callbacks, message brokers in the middle |
| WS-ReliableMessaging | sequence numbers and acknowledgements, with a delivery assurance chosen per sequence: at-most-once, at-least-once, exactly-once or in-order | telecom and ERP integrations over unreliable links |
| WS-Policy | machine-readable statements of what a service requires (which security, which addressing) | negotiating with a partner's stack |
| MTOM / XOP | binary attachments sent as real bytes instead of base64 inside the XML | documents, images, X-rays |
Message-level security is the one that has no REST equivalent in common use. TLS protects the hop; a WS-Security signature stays with the document through a queue, a broker and an archive, and an auditor can verify it a year later. When a bank insists on SOAP, this is usually why.
Where SOAP fits, and where it does not
It fits a partner integration where a contract must be negotiated, validated and audited; where the message, not the connection, must be signed; and where the other side already has it. It does not fit browsers (XML parsing and envelope overhead for nothing), mobile clients on metered links, or any internal service you control both ends of. And it is not a reason to avoid an integration: generated clients make calling a SOAP service a day of work, not a quarter.
5. RPC: calling a function that lives somewhere else
In short. RPC protocols give up URLs and HTTP semantics and get back a typed function call. gRPC is the modern one: protobuf for types, HTTP/2 for transport, streaming in both directions, and status in trailers.
The family tree is short. XML-RPC (1998) put a method name and typed parameters in a small XML document. JSON-RPC 2.0 (2010) did the same with JSON and is still a good choice when you want RPC without a code generator:
--> {"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
Its error object uses reserved numeric codes, which is a cheap way to tell a protocol problem from a business one:
| Code | Meaning |
|---|---|
| −32700 | invalid JSON |
| −32600 | not a valid request object |
| −32601 | method not found |
| −32602 | invalid parameters |
| −32603 | internal error |
| −32000 to −32099 | reserved for your own server errors |
JSON-RPC is transport-agnostic: the same frames travel over HTTP POST, a WebSocket, a pipe or a TCP socket. That is why editors (the Language Server Protocol), Ethereum nodes and plenty of internal daemons use it.
gRPC
gRPC is an RPC system with four parts that are easier to understand separately: protobuf for the contract and the bytes (section 6), HTTP/2 for transport, a call model with four shapes, and a status model of its own.
The service is declared, then both sides generate code:
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
}
On the wire a unary call is one HTTP/2 request whose path is the method and whose body is a sequence of length-prefixed messages:
: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
Each message gets a five-byte prefix: one byte saying whether it is compressed, then a four-byte big-endian length. Here is a real one, wrapping the 39-byte protobuf record from section 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 means uncompressed, 00 00 00 27 is 39, and the rest is the message. Because the length comes first, a receiver always knows where a message ends, which is what makes streaming many messages over one call straightforward.
The status does not travel in the body. It arrives as HTTP/2 trailers after the last message:
grpc-status: 0
grpc-message:
That design is what allows a server to start streaming results before it knows whether the whole operation will succeed, and it is also why gRPC needs HTTP/2 and why a proxy that drops trailers breaks it in a way that is painful to diagnose: the data arrives, the call never completes.
The status codes are a fixed, small set, which is a real advantage over "pick a 4xx":
| Code | Name | Retry? |
|---|---|---|
| 0 | OK | — |
| 1 | CANCELLED | no, the caller gave up |
| 3 | INVALID_ARGUMENT | no, fix the request |
| 4 | DEADLINE_EXCEEDED | maybe, with a longer deadline |
| 5 | NOT_FOUND | no |
| 6 | ALREADY_EXISTS | no, and it often means your retry worked the first time |
| 7 | PERMISSION_DENIED | no |
| 8 | RESOURCE_EXHAUSTED | yes, with backoff |
| 9 | FAILED_PRECONDITION | no, until the state changes |
| 10 | ABORTED | yes, usually a concurrency conflict |
| 12 | UNIMPLEMENTED | no |
| 13 | INTERNAL | no, a bug |
| 14 | UNAVAILABLE | yes, with backoff |
| 16 | UNAUTHENTICATED | no, get a token |
Two practical consequences of the design. Deadlines are part of the protocol: grpc-timeout is sent, propagated to downstream calls and enforced on both sides, which is a discipline most HTTP stacks have to be talked into (timeouts and retries). And a gRPC channel is one long-lived HTTP/2 connection, so a connection-level load balancer pins every call to one backend; balancing needs an L7 proxy or client-side balancing (load balancing, service meshes).
Browsers cannot speak gRPC directly, because they cannot control HTTP/2 frames or read trailers. gRPC-Web fixes that with a slightly different framing and a proxy that translates; bidirectional streaming is not available.
Where RPC fits, and where it does not
gRPC fits internal service-to-service traffic, high call rates, polyglot teams that want one generated contract, and streaming both ways. JSON-RPC fits internal tools and anything that must be debuggable by hand. RPC does not fit public APIs with unknown clients (a URL and curl are a better front door), anything that needs HTTP caching, or a team with no appetite for a build step and a schema registry.
6. Schemas and the bytes they produce
In short. The payload format decides size, speed, and whether a wrong field is caught at build time. The same small record is 39 bytes as protobuf, 122 as compact JSON and 406 inside a SOAP envelope.
One order with two items, serialized three ways and then gzipped (the script in the appendix produced these numbers; they are byte counts of this one record, not a benchmark of your traffic):
| Format | Bytes | Gzipped |
|---|---|---|
| protobuf | 39 | 57 |
| JSON, compact | 122 | 118 |
| SOAP 1.2 envelope, XML | 406 | 258 |
Note the honest surprise: gzip makes the protobuf message bigger, because at 39 bytes the gzip header and dictionary cost more than they save. Compression pays on repetitive text, which is exactly what XML and JSON are. The 10x gap between protobuf and XML closes to about 4.5x once both are compressed, and a single HTTP response header set can be larger than any of them, which is why HTTP/2's header compression mattered so much.
How protobuf gets to 39 bytes
The bytes of that record, from the real library:
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..
There are no field names. Each field is a tag byte that packs the field number and a wire type, then the value. 0a is field 1, wire type 2 (length-delimited), so what follows is a length (05) and five bytes: ord_7. 18 cb 21 is field 3, wire type 0 (varint), carrying 4299.
A varint stores seven bits per byte and uses the top bit to mean "more to come":
varint(1) = 01
varint(300) = ac 02
varint(4299) = cb 21
Small numbers cost one byte, which is why field numbers 1 to 15 fit in a single tag byte and why the protobuf style guide tells you to spend them on the fields that appear most.
The wire types are the whole encoding:
| Wire type | Used for | How it is framed |
|---|---|---|
| 0 | int32, int64, uint*, bool, enum | varint |
| 1 | fixed64, double | 8 bytes |
| 2 | string, bytes, embedded messages, packed repeated fields | varint length, then that many bytes |
| 5 | fixed32, float | 4 bytes |
(Wire types 3 and 4 were the old start-group and end-group markers and are deprecated.)
The evolution rules, which are the real contract
Because the wire carries numbers and not names, protobuf has clear compatibility rules, and they are worth memorising:
- Never reuse a field number. Mark removed fields
reserved; a reused number makes old data decode into the wrong field, silently. - Adding a field is safe. Old code does not know the number and keeps it as an unknown field (proto3 has preserved unknown fields since 3.5, so a proxy does not destroy data it does not understand).
- Renaming a field is safe on the wire and breaks anything using the JSON mapping or generated accessors.
- Changing a type is usually not safe.
int32toint64happens to work for small values;int32tostringdoes not. - In proto3 every scalar has a default and is not sent when it equals the default, so "absent" and "zero" are the same thing unless you mark the field
optional(restored in 3.15) or use a wrapper message.
Compare how each format answers question 6 from section 1:
| Format | Where the schema lives | Adding a field | Removing one | Caught by |
|---|---|---|---|---|
| JSON | nowhere, or OpenAPI beside it | safe if clients ignore extras | breaks whoever read it | tests, or production |
| XML with XSD | the schema, shipped | needs a schema change, often a new namespace | same | a validator, before your code |
| protobuf | the .proto, compiled into both sides | safe | safe if the number is reserved | the compiler, and a schema-registry check in CI |
| GraphQL | the server's schema, introspectable | safe | @deprecated, then watch usage | the schema check in CI |
This is the clearest practical difference between the families. JSON buys speed of change and pays for it in uncertainty; compiled schemas buy certainty and pay for it with a build step.
7. GraphQL: the client names the data
In short. One endpoint, one POST, a query language that says exactly which fields are wanted, and a schema the client can introspect. It solves over-fetching and the twelve-request screen, and it moves caching, authorization and cost control from the infrastructure into your code.
A query and its answer:
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 } ] } } }
The request is a POST of {"query": "...", "variables": {...}, "operationName": "OrderScreen"} to a single URL, with content-type: application/json. Three protocol consequences follow immediately, and they are what people actually trip over.
A failed field comes back with HTTP 200. A GraphQL response can carry data and errors together, because one field may fail while the rest succeeded:
{ "data": { "order": { "id": "ord_7", "customer": null } },
"errors": [ { "message": "Forbidden", "path": ["order","customer"],
"extensions": { "code": "FORBIDDEN" } } ] }
The status code is not always 200, though, and "GraphQL always answers 200" is the simplification that gets teams into trouble. The specification separates a request error, where the document could not be parsed or validated so nothing executed, from a field error raised while executing. Which status you see then depends on the response media type:
application/json, the traditional type | application/graphql-response+json, the type the spec recommends | |
|---|---|---|
| Malformed JSON or an unreadable request | often 400 | 400 |
| A document that fails validation | commonly 200, with errors and no data | 400 |
A field error, with partial data | 200 | 200 |
| Wrong method, or a media type the server will not take | 405, 415 | 405, 415 |
Read "often" and "commonly" as written: GraphQL over HTTP is still a draft, later revisions change some of these codes, and servers differ, so check what yours actually does instead of trusting a table. What holds everywhere is the consequence: a client that branches only on the HTTP status misses field errors, and a dashboard counting non-2xx responses can show a flawless service while every request comes back half-failing. Put your machine-readable code in extensions, alert on the share of responses that contain errors, and ask for the newer media type if you want the status line to carry information.
HTTP caching does not apply. A POST to one URL with a body that differs per screen is uncacheable by any CDN or browser cache. The answers are persisted queries (register the query once, send a hash), GET for queries that are safe to cache, and caching inside the server at the resolver or entity level.
The query is an attack surface. A client can ask for a deeply nested, expensive graph. The protections are depth limits, complexity or cost analysis with a budget per caller, pagination arguments that are mandatory rather than optional, persisted queries in production (so only known queries run), and timeouts per resolver.
The other famous problem is N+1: a list of 50 orders whose customer field triggers 50 database queries. The fix is batching inside the resolver layer (DataLoader-style: collect the ids requested during one tick, fetch them in one query, hand each resolver its slice). This is a server design issue, not a protocol one, but it is the first thing to look for when a GraphQL API is slow.
Subscriptions are not really part of the protocol. The specification defines the operation type, not the transport. In practice subscriptions run over a WebSocket with a sub-protocol (graphql-transport-ws, which replaced the older subscriptions-transport-ws) or over SSE. That means section 8's warnings about long-lived connections apply to GraphQL subscriptions too.
Where GraphQL fits, and where it does not
It fits several different clients with different data needs over one backend, a mobile app that must minimise round trips, and an organisation willing to own the schema as a product. It does not fit a simple CRUD service with one client (it buys nothing and costs a server), file uploads and downloads (HTTP already does that well), or a team that needs CDN caching to carry the load.
8. When the server needs to speak first: WebSocket, SSE and long polling
In short. HTTP's shape is "client asks". Three techniques work around it: hold a request open (long polling), stream a one-way text channel (SSE), or trade the HTTP connection for a two-way frame protocol (WebSocket). Pick the weakest one that does the job, because every long-lived connection is a thing to operate.
WebSocket
A WebSocket starts as an ordinary HTTP request and then stops being 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
That Sec-WebSocket-Accept value is not a secret and not a token. It is base64(sha1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")), with that fixed GUID from RFC 6455. The pair above was computed by the script in the appendix, so you can check it. Its only job is to prove the server understood the upgrade rather than echoing bytes back like a dumb proxy, which also explains why there is no point "validating" it for security.
After the 101 there are no more headers, only frames. A client text frame carrying {"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 is FIN plus opcode 1 (text). 92 is the mask bit plus length 18. The next four bytes are the masking key, and the rest is the payload XORed with it; unmasking gives back the original JSON exactly. So the overhead is six bytes for a client frame (2 header + 4 mask) and two for a server frame, against roughly 100-800 bytes of headers for an HTTP request. That is the real argument for WebSocket: not that it is faster, but that a message costs almost nothing once the connection exists.
The frame details worth knowing:
| Field | Values |
|---|---|
| Opcodes | 0x0 continuation, 0x1 text, 0x2 binary, 0x8 close, 0x9 ping, 0xA pong |
| Masking | mandatory on client-to-server frames, forbidden on server-to-client ones. It exists to stop a crafted payload from poisoning an old proxy |
| Length | 0-125 inline, 126 means a 2-byte length follows, 127 means an 8-byte one |
| Close codes | 1000 normal, 1001 going away, 1002 protocol error, 1008 policy violation, 1009 message too big, 1011 internal error. 1006 means "the connection died" and is never sent on the wire |
| Extensions | permessage-deflate (RFC 7692) compresses payloads; it costs memory per connection |
What the protocol does not give you, and you therefore have to build:
- Reconnection, with backoff and resumption. Networks drop; the protocol says nothing. Clients need a retry with jitter and a way to say "I had event 41" (resilience patterns).
- Request/response correlation. If you want a reply to a message, you invent ids. This is why JSON-RPC over WebSocket is such a common pairing.
- Heartbeats. Load balancers and NATs drop idle connections, often after 60 seconds. Ping/pong frames keep them alive and detect a half-open connection.
- Backpressure. A slow consumer makes the server buffer. You need a bounded queue per connection and a policy for overflow: drop, coalesce or disconnect.
- Authentication after the upgrade. Browsers cannot set headers on a WebSocket handshake, so the token goes in a cookie, a query parameter (which lands in access logs) or a first message after connecting. The last is the cleanest.
- Scale-out. Connections are stateful, so a fan-out needs a bus behind the servers, and the balancer must keep a connection on one node (load balancing).
RFC 8441 allows WebSocket over HTTP/2 via extended CONNECT, which removes the one-connection-per-socket cost; support is uneven. Over HTTP/3 the forward-looking option is WebTransport, which adds unreliable datagrams for cases where a late message is worse than a lost one, such as games.
Server-sent events
If the traffic only flows one way, SSE is a tenth of the work. It is a normal HTTP response that never ends:
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
The rules fit on a postcard: fields are data, event, id and retry; a blank line dispatches the event; a line starting with : is a comment used as a heartbeat. The browser's EventSource reconnects on its own and sends Last-Event-ID with the id it last saw, so a server that honours that header gives you resumable streams for free. It is text only (UTF-8), one-way, and on HTTP/1.1 it occupies one of the six connections a browser allows per origin, which is the usual reason an SSE page mysteriously stops loading other things. Over HTTP/2 the stream is one of many on a single connection, so that bottleneck goes away, but not every limit does: the ceiling becomes the concurrent-stream limit the server advertises in SETTINGS_MAX_CONCURRENT_STREAMS, commonly in the low hundreds.
Long polling, and when it is right
The client sends a request; the server holds it until there is news or a timeout; the client immediately asks again. It is ugly, it works through every proxy ever built, and it needs no new infrastructure. For a notification that arrives a few times an hour it is a perfectly reasonable answer, and it is the fallback every realtime library still ships.
| Long polling | SSE | WebSocket | |
|---|---|---|---|
| Direction | server to client, one message per request | server to client, continuous | both ways |
| Transport | plain HTTP | plain HTTP | HTTP upgrade, then frames |
| Payload | anything | UTF-8 text | text or binary |
| Reconnect and resume | you write it | built in (Last-Event-ID) | you write it |
| Proxy and firewall trouble | almost none | little (watch response buffering) | some (upgrade must be allowed, idle timeouts) |
| Cost per message | a full request and response | a few bytes | 2 to 6 bytes |
| Good for | rare notifications | tickers, progress, logs, feeds | chat, collaboration, games, trading |
The honest default: SSE until you need to send upstream, then WebSocket. Most "we need WebSockets" projects are a one-way feed plus occasional POSTs, and that combination is simpler to operate, debug and cache.
9. Webhooks: HTTP with the arrow reversed
In short. A webhook is somebody else's system making an HTTP request to your URL when something happens. The protocol is trivial; the engineering is all in signatures, retries, ordering and idempotency.
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}}
The receiver's checklist, in order, because the order matters:
- Verify the signature on the raw bytes, before parsing. The usual scheme is HMAC-SHA256 over the id, the timestamp and the exact body, with a shared secret. Re-serializing the JSON first changes the bytes and breaks the check.
- Reject old timestamps (a few minutes' window), or a captured request can be replayed forever.
- Answer 2xx quickly, then work. Senders time out in seconds. Store the event and process it asynchronously; do not do the invoice run inside the handler.
- Deduplicate on the event id. Retries, at-least-once delivery and your own 500s mean the same event will arrive twice (idempotency).
- Do not assume order.
payment.succeededcan arrive beforeorder.created. Either tolerate it, or fetch the current state from the sender's API and treat the webhook purely as a nudge: the "thin payload" pattern, which also avoids trusting data you did not fetch. - Expect your endpoint to be probed. Validate the content type and size, cap the body, and keep the handler free of anything that runs on untrusted input (web application security).
On the sending side the obligations mirror these: retry with exponential backoff and a cap, show the customer a delivery log with the response codes, sign every attempt, allow endpoint rotation with two live secrets during the change, and disable an endpoint that has failed for days instead of hammering it. If you cannot be called back at all (no public URL), the remaining options are polling with a cursor or a message broker both sides can reach (section 10).
10. Messaging protocols: AMQP, MQTT, STOMP
In short. These protocols put a broker between the sender and the receiver, so the two never have to be online at the same time. AMQP is the enterprise work-queue protocol, MQTT is the small-device protocol, STOMP is the simple text one. What they buy you is decoupling; what they cost you is a broker to run and a new set of failure modes.
The patterns, the delivery guarantees and the operational side are covered in message queues and delivery guarantees. This section is about the protocols themselves.
AMQP 0-9-1, and the trap in the version number
AMQP 0-9-1 is what RabbitMQ speaks (port 5672, 5671 with TLS). Its model is three nouns: a publisher sends to an exchange with a routing key; bindings connect exchanges to queues; consumers read from queues. Exchange types decide the routing: direct (exact key), topic (orders.*.eu patterns), fanout (everywhere) and headers. One TCP connection carries many channels, so a process does not need a connection per thread.
The protocol features that matter in production:
- Publisher confirms: without them,
basic.publishis fire-and-forget and a broker restart loses messages you believe were sent. - Consumer prefetch (
basic.qos): the number of unacknowledged messages a consumer may hold. Leave it unlimited and one consumer grabs the whole queue; set it to 1 and you pay a round trip per message. - Ack, nack and reject, with a
requeueflag. Requeueing a message that always fails is how a poison message spins forever, so pair it with a dead-letter exchange and a redelivery count. - Queue and message TTLs, and dead-letter exchanges: the only way to keep a stuck queue from growing until the disk is full.
AMQP 1.0 is a different protocol with the same name. It was standardised by OASIS and as ISO/IEC 19464, and it describes symmetric peers exchanging messages over links with credit-based flow control, not the exchange/queue model. Azure Service Bus and ActiveMQ speak it; a 0-9-1 client cannot talk to a 1.0-only broker. When someone says "it is AMQP, so it will interoperate", ask which version.
MQTT, for links you do not control
MQTT (port 1883, 8883 with TLS) was designed for devices on slow, expensive, unreliable links, and the design shows in the byte counts. A whole CONNECT packet, built by hand in the appendix script:
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 is the packet type (CONNECT), 15 is the remaining length (21 bytes), then the protocol name MQTT, level 4 (which means MQTT 3.1.1), the flags, a 60-second keep-alive and the client id. A publish of a temperature reading with 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
Twenty-two bytes carry the topic, a packet id and the reading 21.5; the acknowledgement (PUBACK) is four bytes. The leanest possible HTTP/1.1 POST of the same four bytes is 103 bytes before any response, any TLS and any retry. On a battery-powered sensor reporting every minute over a cellular link, that ratio is the product decision.
The parts of MQTT you must understand before using it:
| Feature | What it does | The catch |
|---|---|---|
| QoS 0 | fire and forget | lost on any hiccup, and that is often fine for a sensor |
| QoS 1 | at least once, acknowledged | duplicates, so the receiver must be idempotent |
| QoS 2 | exactly once, four-step handshake | the slowest and the most state per message; rarely worth it |
| Retained message | the broker keeps the last message per topic and gives it to new subscribers | it is not history, only the newest value, and it persists until replaced |
| Last Will and Testament | the broker publishes a message if a client disappears | the only way others learn a device went offline |
| Keep-alive | a heartbeat interval agreed at CONNECT | a half the interval rule of thumb for the client's own timer |
| Clean session / session expiry | whether subscriptions and queued messages survive a disconnect | a persistent session on a chatty topic can make the broker store a lot |
| Wildcards | + matches one level, # matches the rest and must be last | # at the root subscribes to everything, including other tenants' topics |
MQTT 5 is worth asking for: it adds reason codes on every acknowledgement (so a rejected publish says why), user properties (arbitrary key/value headers, which is where a correlation id belongs), shared subscriptions ($share/group/topic, so a topic can be load balanced across workers), topic aliases, message expiry and real flow control. MQTT 3.1.1 answers most failures with a closed connection and no reason.
Note what MQTT does not have: no schema, no request/response (MQTT 5 adds a response-topic convention), no ordering guarantee across topics, and authorisation is the broker's job, usually per topic pattern. Topic design is the API design, and it is also the security boundary: tenant/{id}/# is the pattern that keeps tenants apart.
STOMP, and Kafka's protocol
STOMP is a text protocol (CONNECT, SEND, SUBSCRIBE, MESSAGE, ACK) that looks like HTTP and is trivial to implement. Its common home is a browser talking to a broker over a WebSocket, which is what Spring's messaging stack does.
Kafka does not speak AMQP or MQTT. It has its own binary, length-prefixed TCP protocol, and the model is different enough to matter: a partitioned, append-only log with consumer-managed offsets, rather than queues that drain. Choosing between a queue and a log is an architecture decision, not a protocol one; the queues guide covers it.
Where messaging fits, and where it does not
It fits work that may take longer than a request, traffic spikes that must be absorbed, several consumers of one event, systems that are not up at the same time, and devices on bad links. It does not fit a client waiting for an answer right now (a queue plus a reply queue is a slow, fragile RPC), simple internal calls between two services you deploy together, or any team that is not ready to monitor queue depth and consumer lag.
11. The survivors: SMTP, IMAP, FTP, SFTP and SSH
In short. Mail and file transfer are the protocols you inherit rather than choose. They are worth a page because the failure modes are specific, old and still cost people days.
SMTP
SMTP (RFC 5321) is a line-based conversation where every answer is a three-digit code. The shape of a submission:
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
The details that cause real incidents:
- The ports mean different things. 25 is server-to-server relay and is blocked by most networks and cloud providers for outbound mail; 587 is authenticated submission (RFC 6409) with STARTTLS; 465 is submission over implicit TLS and is recommended again by RFC 8314. Code that cannot send mail from a new host is usually pointed at 25.
- 4xx is "try later", 5xx is "never". A sender that treats 450 as permanent loses mail; one that retries 550 forever gets itself blocked.
- A line containing only a dot ends the message, so a body line starting with a dot must be doubled (dot-stuffing). Every mail library does this; hand-rolled senders are where it breaks.
- The envelope sender is not the
From:header. Bounces go to the envelope address, and the mismatch is what SPF checks. - Deliverability is DNS, not SMTP. SPF, DKIM and DMARC are DNS records plus a signature header; without them a technically perfect SMTP conversation lands in spam.
Reading mail is a different protocol: IMAP (IMAP4rev2, RFC 9051; ports 143 and 993) keeps the messages on the server with folders, flags and server-side search, while POP3 (110 and 995) is a download-and-delete model from a time when one person used one device.
FTP, FTPS, SFTP, SCP
FTP (RFC 959) uses two connections: a control channel on port 21 for commands, and a separate data connection per transfer. That is its whole problem. In active mode the server connects back to a port the client names with PORT, which almost no firewall or NAT allows any more; in passive mode (PASV, or EPSV for IPv6) the server names a port and the client connects, which works but means the server must expose a port range. Half of all FTP support tickets are "the listing works, the transfer hangs", and that is active mode meeting a NAT.
| FTPS | SFTP | SCP | |
|---|---|---|---|
| What it is | FTP with TLS (AUTH TLS, RFC 4217) | a file-transfer subsystem of SSH, on port 22 | a copy command, historically its own protocol |
| Relation to FTP | the same protocol, encrypted | unrelated, despite the name | unrelated |
| Ports | 21 plus a data range | one, 22 | 22 |
| Firewall friendliness | poor (the data range) | good | good |
| Features | directory listing, resume | listing, resume, attributes, partial reads and writes | copy only |
The practical advice is short: use SFTP. It is one port, authenticated and encrypted by SSH, scriptable, and it is what partners mean nowadays when they say "FTP". OpenSSH 9.0 even made scp use the SFTP protocol underneath, because the old SCP protocol had a long history of surprises. Use FTPS only when the other side insists, and if you must run an FTP server, run passive mode with a fixed, open port range and log which mode each client used.
SSH, underneath all of that
SSH (RFC 4251 to 4254) is three layers: a transport layer that negotiates algorithms, exchanges keys and authenticates the server with its host key; a user authentication layer (public key, password, keyboard-interactive); and a connection layer that multiplexes channels over the one encrypted stream. Channels are why one SSH connection can carry a shell, a file transfer and three forwarded ports at once.
Two things follow from that structure. The host key check is trust on first use: the fingerprint saved in known_hosts on the first connection is what later warns you about a man in the middle, so blindly accepting a changed key throws the protocol's main guarantee away. And port forwarding (-L, -R, -D) is a channel like any other, which is why SSH is the universal tool for reaching a database that is not exposed, and also why it is the first thing a security review looks at.
12. The concerns that cut across all of them
In short. Ports, authentication, error vocabulary, versioning, tracing and what to measure look different in each protocol but are the same six problems. Knowing the mapping is most of what "experienced with protocols" means.
Ports, in one table
| Protocol | Plain | With TLS | Note |
|---|---|---|---|
| HTTP | 80 | 443 | 443 is the only port you can rely on crossing a corporate network |
| WebSocket | 80 (ws://) | 443 (wss://) | it is HTTP until the 101 |
| gRPC | — | 443, or any port internally | HTTP/2, so the same ports as HTTP |
| SMTP | 25 relay, 587 submission | 465 submission, or STARTTLS on 587 | outbound 25 is blocked nearly everywhere |
| IMAP / POP3 | 143 / 110 | 993 / 995 | |
| FTP | 21 plus data | 21 with AUTH TLS (FTPS) | the data channel is the problem, not the port |
| SSH, SFTP | 22 | 22 (SSH is always encrypted) | one port for shell, transfer and forwarding |
| AMQP 0-9-1 | 5672 | 5671 | RabbitMQ's management UI is 15672, a different thing |
| MQTT | 1883 | 8883 | MQTT over WebSocket uses the web ports, or one the broker picks |
| DNS | 53 | 853 (DoT), 443 (DoH) | see the DNS guide |
Authentication, by protocol
| Protocol | Usual mechanisms | The sharp edge |
|---|---|---|
| HTTP, REST, GraphQL | Authorization: Bearer (RFC 6750), Basic (RFC 7617), cookies, API keys, mTLS | a token in a URL query parameter ends up in logs, caches and referrers |
| gRPC | metadata headers (authorization), or mTLS with per-channel credentials | metadata is per call, but a channel is long-lived: refresh tokens need a call-time credential, not a connection-time one |
| SOAP | WS-Security headers (username token, X.509 signature), or HTTP Basic plus TLS | message-level signatures survive brokers and archives; transport auth does not |
| WebSocket | cookie on the handshake, token in the first message, or a short-lived ticket in the URL | browsers cannot set headers on the handshake, so the design is forced |
| AMQP, MQTT | username and password at connect, client certificates, broker ACLs per queue or topic | authorisation is the broker's, not the application's: get the topic or queue patterns right |
| SMTP | SASL on the submission port | authentication says who may send, not what address they may claim |
| SSH, SFTP | public key, certificates, (passwords) | the host key is the client's only protection; an accepted change is an accepted attacker |
Sessions, tokens and their lifetimes are their own subject: authentication and sessions.
The same failure, said six ways
This is the table I wish I had when I started. One row is one real situation, and the columns are how each protocol expresses it.
| Situation | HTTP / REST | gRPC | GraphQL | JSON-RPC | SOAP | MQTT 5 |
|---|---|---|---|---|---|---|
| Malformed request | 400 | 3 INVALID_ARGUMENT | 400, or 200 with errors and no data (section 7) | −32600 / −32602 | Sender fault | reason code 0x81 |
| Not authenticated | 401 | 16 UNAUTHENTICATED | 200 with an auth error | custom | security fault | 0x87 at connect |
| Authenticated, not allowed | 403 | 7 PERMISSION_DENIED | errors with a path and null field | custom | Sender fault | 0x87 on publish |
| Thing does not exist | 404 | 5 NOT_FOUND | null plus an error | custom | application fault | — |
| Conflict with current state | 409 / 412 | 10 ABORTED, 9 FAILED_PRECONDITION | errors | custom | application fault | — |
| Too many requests | 429 with Retry-After | 8 RESOURCE_EXHAUSTED | errors | custom | 0x97 quota exceeded | — |
| Server broke | 500 | 13 INTERNAL | errors | −32603 | Receiver fault | — |
| Temporarily down | 503 with Retry-After | 14 UNAVAILABLE | errors | −32603 | Receiver fault | connection closed |
| Took too long | 504 | 4 DEADLINE_EXCEEDED | errors | timeout | timeout | keep-alive timeout |
Read the columns and two protocol-level lessons appear. First, the protocols that separate "do not retry" from "retry later" make clients much easier to write: HTTP (4xx against 429, 503) and gRPC (INVALID_ARGUMENT against UNAVAILABLE) do; GraphQL and MQTT 3.1.1 mostly do not, so you must encode it yourself in extensions or in a payload field. GraphQL's status line says something only once you negotiate the newer media type, and even then only about request errors. Second, a protocol that answers 200 or closes the connection for everything forces every client to parse prose, which is how retry storms begin.
Versioning, by protocol
| Protocol | How a version is expressed | Additive change | Breaking change |
|---|---|---|---|
| REST | path (/v2/orders), media type (application/vnd.shop.v2+json), or a header | add a field, ignore unknown ones | a new version, both served for a while |
| GraphQL | normally none: one evolving schema | add fields and types | @deprecated, measure usage, then remove |
| gRPC, protobuf | the package name (shop.v2) | add a field with a new number | a new service or package; never reuse a field number |
| SOAP | a new target namespace and WSDL URL | a new optional element, if the schema allows it | a new namespace; the old one keeps running |
| JSON-RPC | the method name (orders.get.v2) | add an optional parameter | a new method name |
| MQTT, AMQP | the topic or routing key, and a version field in the payload | a new field, if the consumer tolerates it | a new topic, with both published during the change |
The pattern across all of them: adding is cheap, removing is a project. Every protocol above gives you a way to add and a way to run two versions side by side; none gives you a way to delete something clients still use.
Correlation and tracing
One field, carried everywhere, is what makes a request traceable across protocols. The W3C Trace Context header is the common form:
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
| Protocol | Where it goes |
|---|---|
| HTTP, REST, GraphQL | the traceparent header |
| gRPC | metadata, which is HTTP/2 headers, so the same name |
| AMQP | a message header or application property |
| MQTT 5 | a user property; in 3.1.1 there is nowhere but the payload |
| SOAP | a header element, usually WS-Addressing's MessageID |
| Webhooks | a header the sender defines; log their event id as well as yours |
The reason to care is that a request crossing four protocols with no shared id is four separate investigations (observability).
What to measure, per protocol
No guide can tell you your numbers. It can tell you which four signals are worth a dashboard.
| Protocol | Watch |
|---|---|
| HTTP, REST | request rate, latency percentiles per route, status-class rates, and the share of 304s and cache hits |
| GraphQL | the share of responses carrying errors, resolver time per field, query depth and cost, and the top queries by cost |
| gRPC | status-code counts (not just error rate), deadline-exceeded share, message sizes, and per-connection call distribution |
| WebSocket, SSE | open connections, connections per node, message rate, ping failures, and send-buffer depth |
| Webhooks (sending) | delivery success, attempts per event, age of the oldest pending event, endpoints disabled |
| AMQP, MQTT | queue depth and consumer lag, redelivery counts, dead-lettered messages, and broker memory |
| SMTP | accepted against deferred against bounced, and DMARC reports |
13. Choosing
In short. Pick by who starts the conversation, who the clients are, and how strict the contract must be. In that order.
Diagram: Choosing a protocol
The same thing as a table, with the cost you are accepting:
| Situation | Use | What you accept |
|---|---|---|
| A public or partner-facing API | REST over HTTP with JSON | no schema enforcement unless you add OpenAPI and check it in CI |
| Internal calls, many per second, several languages | gRPC | a build step, a schema registry, and proxies that must handle HTTP/2 trailers |
| One backend, several very different front ends | GraphQL | caching, cost control and authorization become your code |
| A bank, an insurer, a government body on the other side | SOAP | verbosity, and 5xx on business errors |
| Live updates to a browser | SSE, then WebSocket if you need upstream | long-lived connections to operate and scale |
| Another company must tell you about events | webhooks | signature checks, replays, duplicates and no ordering |
| Work that must not be lost and may be slow | AMQP or a log | a broker to run, and queue depth to watch |
| Battery-powered or metered devices | MQTT | no schema, and topic design as your security boundary |
| Files between companies | SFTP | key management, and a transfer that is not a transaction |
| SMTP, through a provider | deliverability is DNS and reputation, not code |
Three defaults worth stating plainly, because they save the most time:
- HTTP and JSON until something hurts. It is the only option every client, proxy, log, test tool and new hire already understands. Trade it away for a measured reason, not for a preference.
- Two protocols are a normal answer. A typical system is REST at the edge, gRPC or a queue inside, SSE for live updates, and SFTP because a partner insists. The mistake is not having several; it is having several that say the same thing differently.
- Changing protocol rarely fixes latency. A protocol change buys bytes and round trips; a waterfall of five dependent calls costs five times the latency whatever the protocol. Count the round trips first (DNS, HTTP/2 and waterfalls).
Migrating without a rewrite
| From | To | The usual route |
|---|---|---|
| SOAP | REST or gRPC | keep the SOAP endpoint, add the new one in front of the same service layer, move clients one at a time, and keep a generated SOAP client for the partners who will never move |
| REST | gRPC internally | introduce it for one chatty pair of services, keep REST at the edge; a gateway can translate (grpc-gateway, Envoy) |
| REST polling | SSE or WebSocket | ship SSE for the feed first and keep polling as the fallback; the client code for both is similar |
| Polling a partner | webhooks | accept webhooks as a nudge, keep the polling job at a low frequency as a safety net |
| A queue used as RPC | gRPC or HTTP | if the caller waits for the answer, it was never messaging |
14. Common mistakes
- Treating a SOAP fault's HTTP 500 as "the server is broken" in monitoring, and paging someone for a business error.
- Sending a SOAP 1.2 envelope (or no
SOAPAction) to a SOAP 1.1 endpoint and concluding the service is down. - Retrying a POST or a PATCH after a timeout without an idempotency key.
- Treating PATCH as idempotent because your own patches happen to be, and expecting a proxy or a retry layer to know that.
- Using 200 for everything, or 500 for client mistakes, and making every client parse the body.
- Returning GraphQL errors and alerting only on HTTP status codes, so a half-broken API looks perfect.
- Letting a GraphQL client send any query in production: no depth limit, no cost budget, no persisted queries.
- Expecting a CDN to cache a POST, whether it is GraphQL or an RPC endpoint.
- Reusing a protobuf field number, or deleting a field without reserving it.
- Assuming
optionalbehaviour from proto3 scalars: a zero and an absent value are the same unless you asked for presence. - Putting a gRPC service behind a proxy that drops HTTP/2 trailers, then debugging "the call never finishes".
- Balancing gRPC with a TCP load balancer, so one backend gets every call on each channel.
- Opening a WebSocket when the traffic is one-way, and inheriting reconnection, heartbeats and sticky routing for nothing.
- Forgetting heartbeats, then blaming the network for connections that die after exactly 60 seconds.
- Parsing a webhook body before verifying its signature, or verifying a re-serialized copy of it.
- Processing a webhook synchronously, timing out the sender, and getting the same event five more times.
- Assuming webhook events arrive in order, or exactly once.
- Choosing MQTT QoS 2 by default, or treating a retained message as a message history.
- Subscribing to
#in a multi-tenant broker. - Saying "we use AMQP" without saying 0-9-1 or 1.0.
- Sending mail from port 25 on a cloud host, or treating a 4xx SMTP reply as permanent.
- Running FTP in active mode across a NAT, or thinking SFTP is FTP with TLS.
- Accepting a changed SSH host key because it was faster than asking why.
- Quoting a message-size table (including this guide's) as if it predicted your latency.
15. Things to mention in an interview
- "A protocol is six decisions: framing, addressing, who speaks first, schema, errors and evolution. Most protocol arguments are really one of those six in disguise."
- Safe and idempotent are the two words that matter in HTTP: they decide what a crawler may fetch and what a retry may repeat. GET, HEAD, PUT and DELETE are idempotent and POST is not; PATCH is not idempotent as a method, although a given patch document may be, and that distinction is the one interviewers are listening for.
- 401 is "I do not know you", 403 is "I know you and no", 429 and 503 are invitations to come back, and 500 is not.
- A conditional request with
ETagandIf-None-Matchturns a repeated read into a 304 with no body;If-Matchon a write gives optimistic concurrency with a 412. - SOAP's value is the contract and message-level security (WS-Security), not the XML; its oddity is that faults arrive as HTTP 500.
- gRPC is protobuf plus HTTP/2: five-byte length prefixes, metadata as headers, the status in trailers, deadlines propagated with the call. Browsers need gRPC-Web, and a channel is one connection, which is why balancing needs L7.
- Protobuf's wire format carries field numbers, not names, which is why adding a field is safe, reusing a number is dangerous, and renaming is free on the wire but breaks the JSON mapping.
- A GraphQL field error comes back as 200 with an
errorsarray, so status-based monitoring misses it; a request error can be a 400, depending on the media type and the draft the server follows. GraphQL also loses CDN caching, and it needs depth and cost limits, batching for N+1, and persisted queries. - SSE is a one-way text stream with built-in reconnection and
Last-Event-ID; WebSocket is two-way frames after a 101 upgrade, with client masking and no reconnection, correlation or backpressure of its own. - Webhooks: verify the HMAC on the raw body, reject old timestamps, answer 2xx fast, deduplicate by event id, and never assume order.
- MQTT is for bad links: a 22-byte publish against a 103-byte HTTP POST, QoS 0/1/2, retained messages, wills, and topics as the security boundary. AMQP 0-9-1 and AMQP 1.0 are different protocols.
- "Use SFTP" is the whole answer to file transfer; SFTP is SSH, not FTP, and it needs one port.
- And the judgement answer: HTTP with JSON until something hurts; change protocol for a measured reason, and expect to run two for a while.
Quick recap
- Every protocol answers six questions: framing, addressing, who speaks first, schema, errors, evolution.
- HTTP's vocabulary (methods, status codes, conditional requests,
Vary) is what makes caches, proxies and retries work; REST is using it on purpose. Safe and idempotent are properties of the method, except for PATCH, where the patch document decides. - SOAP buys a compiled contract and message-level security with verbosity and HTTP 500 faults; it is a day of work to call, not a quarter.
- gRPC is protobuf over HTTP/2 with length-prefixed messages, status in trailers and deadlines in the protocol; it is for internal, high-rate, multi-language traffic.
- Protobuf carries numbers, not names: add freely, never reuse a number, and expect a build step.
- GraphQL moves the choice of fields to the client and the cost of caching, authorization and query limits to you; a failed field is a 200 with
errors, while a rejected document may be a 400. - SSE for one-way push, WebSocket when you need both directions, long polling when the network is hostile.
- Webhooks need signatures, replay windows, fast acknowledgements, deduplication and no assumptions about order.
- AMQP for work queues, MQTT for devices on bad links, a log when you need replay; all of them trade coupling for a broker to operate.
- SMTP's ports and 4xx/5xx distinction, FTP's data connection, and SFTP being SSH are the three legacy facts that keep costing people days.
- Measure before switching: a protocol change buys bytes and round trips, not a different architecture.
Appendix: the demonstration script
Everything quoted as bytes in this guide came from one script: protocols.py, Python 3.13 and the standard library, plus curl for the HTTP part and the protobuf package for the one cross-check that a real library parses the bytes shown. It starts a local HTTP server on 127.0.0.1, so it touches no network, and it prints each exchange, hex dump and byte count in the order the guide quotes them.
# 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)
Two things the script deliberately does not do: it does not measure throughput or latency (a loopback socket would tell you nothing about a real network), and it does not implement any protocol fully. It produces the bytes the specifications describe, so that the numbers in this guide can be checked rather than believed.
Sources
- IETF, HTTP: RFC 9110 semantics, RFC 9111 caching, RFC 9112 HTTP/1.1, RFC 9113 HTTP/2, RFC 9114 HTTP/3 and RFC 5789 PATCH.
- IETF, RFC 9457: Problem Details for HTTP APIs (which obsoletes RFC 7807).
- IETF, RFC 6455: The WebSocket Protocol, RFC 7692 permessage-deflate and RFC 8441: Bootstrapping WebSockets with HTTP/2.
- WHATWG, Server-sent events in the HTML standard.
- W3C, SOAP 1.2 Part 1: Messaging Framework, SOAP 1.1 and WSDL 1.1.
- OASIS, WS-Security 1.1.1 and MQTT 5.0; MQTT 3.1.1.
- JSON-RPC working group, JSON-RPC 2.0 specification.
- gRPC authors, gRPC over HTTP/2, status codes and deadlines.
- Google, Protocol Buffers: encoding and proto3 language guide.
- GraphQL Foundation, the GraphQL specification and serving over HTTP.
- AMQP: AMQP 0-9-1 specification and the RabbitMQ model; OASIS AMQP 1.0.
- IETF, mail and transfer: RFC 5321 SMTP, RFC 6409 submission, RFC 8314 TLS for submission and access, RFC 9051 IMAP4rev2, RFC 959 FTP, RFC 4217 FTP over TLS and RFC 4251 SSH architecture.
- W3C, Trace Context (the
traceparentheader). - Roy T. Fielding, Architectural Styles and the Design of Network-based Software Architectures, chapter 5 (REST).
- MDN Web Docs, HTTP and the WebSockets API.
Practise this topic: Networking & APIs