REST, SOAP & API Styles

"Use REST" is the default answer and it is often wrong, particularly inside large organisations.

SOAP is a protocol, not a style. Messages are XML documents with an envelope containing an optional header and a body, and errors come back as a structured SOAP Fault rather than a status code. A WSDL document describes the service formally — operations, types, bindings — which means clients can be generated from it, strongly typed, with the contract enforced by machine rather than convention.

It is transport-agnostic: SOAP over HTTP is common, but SOAP over message queues is why it persists in banking and telecom. The WS-* family adds message-level security, reliable messaging, and distributed transactions as standards rather than as things each team reinvents. WS-Security signs and encrypts the message, so it survives being relayed through intermediaries — which TLS, protecting only the hop, does not.

SOAP is verbose, heavier to parse, and unpleasant from a browser. It is also still the correct answer when you need a formal contract, message-level security, or integration with systems that already speak it.

REST is an architectural style over HTTP: resources identified by URLs, manipulated with standard verbs, with the protocol's caching, status codes, and tooling for free. It has no built-in contract — OpenAPI is a convention layered on top, not part of the style.

gRPC is for service-to-service: binary protobuf over HTTP/2, generated clients, real streaming, and an interface definition that is genuinely enforced. Awkward from a browser without a proxy.

GraphQL solves over-fetching for many differently-shaped clients, and moves complexity into caching and query cost control.

The honest heuristic: public and browser-facing, REST. Internal service-to-service at volume, gRPC. Many client shapes over one graph of data, GraphQL. Enterprise integration, formal contracts, or an existing SOAP estate — SOAP, without embarrassment.