Loading...
System Design and AI Engineering, by Roni Das. 974 interactive lessons.
Start LearningThe short answerREST is a style for web APIs where each URL is a thing and HTTP methods like GET and POST act on it, usually with small JSON bodies, while SOAP is a strict protocol where every call is an XML envelope posted to one address and described by a WSDL contract, so choose REST for most new APIs and SOAP when a partner system, often in banking, insurance or government, already speaks it.
Representational State Transfer
the address book
Simple Object Access Protocol
the formal letter
Read across a row to compare one thing. Every word that may be new is explained just below the table.
| Aspect | REST | SOAP |
|---|---|---|
| What it is | An architectural style (Fielding, 2000). | A protocol with a written standard (W3C SOAP 1.1 note, 2000; SOAP 1.2, 2007). |
| Message format | Any. Usually JSON. Ours: 69 bytes for one user. | XML only, inside an Envelope. Ours: 391 bytes for the same user. |
| How a call is addressed | By URL and method: GET /users/1. | By operation name inside the body: <get_user>, POSTed to one URL. |
| Contract | Optional (OpenAPI). Our REST endpoint had none. | WSDL, usually required. Ours was 2,878 bytes. |
| Errors | HTTP status codes. Ours: 404 with a small JSON body. | A SOAP Fault. Ours: HTTP 500 with a Fault code and reason. |
| Type checking | Up to your code or your OpenAPI tooling. | Built in through the XML Schema in the WSDL. Ours rejected 'one' as not an integer. |
| Caching | GET responses can be cached by browsers and CDNs. | Usually POST, so standard HTTP caches do not help. |
| Security | HTTPS plus tokens (OAuth, API keys). | HTTPS, plus optional WS-Security for signing or encrypting the message itself. |
| Where you meet it | Public web and mobile APIs, most new services. | Banks, insurers, airlines, payment networks, government systems, older enterprise software. |
Real situations, and the pick we would make in each one.
Small JSON, cacheable GETs, and every language has easy HTTP tools. This is where REST is the default.
You speak the language the other side speaks. Tools like zeep read the WSDL and build the calls for you.
WS-Security signs and encrypts the XML message itself, not just the connection. HTTPS protects only one hop at a time.
In our test the same user cost 69 bytes as JSON and 391 bytes as a SOAP envelope.
Keep REST for your apps and let one gateway translate to SOAP behind it, so the XML lives in one place.
Neither is the usual pick here. Teams often choose gRPC, which sends compact binary messages over HTTP/2.
we ran this, here is what happened
Comparisons usually say SOAP is "heavier". We wanted to know by how much, with real messages.
We wrote one tiny service with one user in it and offered it two ways on one laptop: a REST endpoint (GET /users/1, JSON) and a real SOAP service built with the Python library spyne, which also publishes a WSDL. Then we called both with curl and kept the raw bodies.
We also asked each for a user that does not exist, used the zeep SOAP client to read the WSDL and make the call, and called a public SOAP service (the DNE Online calculator) to show a real one in the wild.
Where it ran: Apple M4, macOS 15.6, Python 3.11 with spyne 2.14.0 (it does not import on 3.12 or newer), lxml, zeep 4.3.1, curl 8.7.1. Local services on 127.0.0.1, plus www.dneonline.com. One run on 4 October 2026.
ENVELOPE='<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="urn:lab.users"><soapenv:Body><u:get_user><u:user_id>1</u:user_id></u:get_user></soapenv:Body></soapenv:Envelope>'
curl -si http://127.0.0.1:8792/users/1
curl -si -H 'Content-Type: text/xml; charset=utf-8' -H 'SOAPAction: "get_user"' --data-binary "$ENVELOPE" http://127.0.0.1:8791/
c = zeep.Client("http://127.0.0.1:8791/?wsdl")
u = c.service.get_user(1)$ curl -si http://127.0.0.1:8792/users/1
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 69
{"id": 1, "name": "Asha", "email": "asha@example.com", "plan": "pro"}
HTTP/1.0 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 391
<?xml version='1.0' encoding='UTF-8'?>
<soap11env:Envelope xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="urn:lab.users"><soap11env:Body><tns:get_userResponse><tns:get_userResult><tns:id>1</tns:id><tns:name>Asha</tns:name><tns:email>asha@example.com</tns:email><tns:plan>pro</tns:plan></tns:get_userResult></tns:get_userResponse></soap11env:Body></soap11env:Envelope>
$ curl -si http://127.0.0.1:8792/users/99
HTTP/1.0 404 Not Found
{"error": "not_found", "message": "no user with that id"}
$ (SOAP get_user(99))
HTTP/1.0 500 Internal Server Error
<soap11env:Envelope xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/"><soap11env:Body><soap11env:Fault><faultcode>soap11env:Client.NotFound</faultcode><faultstring>no user with id 99</faultstring><faultactor></faultactor></soap11env:Fault></soap11env:Body></soap11env:Envelope>
## 4. sizes, in bytes
rest_request_body 0
rest_response_body 69
soap_request_body 197
soap_response_body 391
soap_wsdl 2878
## 6. a SOAP client that reads that contract: zeep
operations the WSDL lists: ['get_user']
get_user(1) -> {'id': 1, 'name': 'Asha', 'email': 'asha@example.com', 'plan': 'pro'}
get_user('one') -> Fault: :2:0:ERROR:SCHEMASV:SCHEMAV_CVC_DATATYPE_VALID_1_2_1: Element '{urn:lab.users}user_id': 'one' is not a valid value of the atomic type 'xs:integer'.
get_user(99) -> zeep.exceptions.Fault: soap11env:Client.NotFound / no user with id 99
## 7. a public SOAP service: DNE Online calculator (http://www.dneonline.com/calculator.asmx)
operations: ['Add', 'Divide', 'Multiply', 'Subtract']
Add(2, 3) -> 5| What we measured | REST | SOAP |
|---|---|---|
| Request body for get user 1the SOAP envelope names the operation | 0 bytes (GET) | 197 bytes |
| Response body for the same user5.7 times larger, uncompressed | 69 bytes | 391 bytes |
| Contract the client reads firstREST can add OpenAPI, optionally | none needed | 2,878-byte WSDL |
| Unknown userSOAP 1.1 uses 500 for faults | HTTP 404 + JSON | HTTP 500 + SOAP Fault |
| Wrong type ('one' for an integer)spyne validated against the WSDL types | not tested | rejected by the schema |
What this shows
For the same four fields SOAP sent 5.7 times more bytes, and a client first had to read a 2,878-byte contract. In return that contract let zeep build the call with no hand-written XML, and the server refused a wrong type before our code ever ran. REST was smaller and simpler; SOAP was stricter. That is the real trade.
What this test does not show: One small record, uncompressed. With gzip both shrink and the gap narrows. Byte size is rarely the reason to choose; contracts, partners and tooling usually are. We did not test WS-Security. The script is scripts/labs/compare/rest_vs_soap.sh in our repository.
"REST is a protocol, like SOAP."
REST is a style of design. SOAP is a protocol with a written standard. A REST API can use JSON, XML or anything else; SOAP always uses an XML envelope.
"SOAP is more secure than REST."
Both normally run over HTTPS. SOAP adds an option, WS-Security, to sign or encrypt the message itself. If you do not use it, SOAP is no more secure than REST.
Building SOAP XML by hand with string templates.
Use a client that reads the WSDL, such as zeep for Python. It builds valid envelopes and turns Faults into exceptions, as our lab shows.
Calling any JSON over HTTP "REST".
An API where everything is POST /doThing with a JSON body is closer to remote procedure calls. REST means resources with URLs and the right HTTP methods.
Rewriting a partner's working SOAP integration in REST for fashion.
If the other side only speaks SOAP, you cannot change that. Wrap it once behind your own REST gateway instead.
Not by default. Both usually run over HTTPS, which encrypts the connection. SOAP has an extra standard, WS-Security (OASIS, version 1.1.1 in 2012), that can sign or encrypt the message itself so it stays protected across several middle systems. Only that option adds security.
When the system you must talk to already offers SOAP, such as many bank, insurance, airline and government services, or when a contract requires message-level signing. For a new API you control, REST is usually simpler.
REST messages are smaller (69 bytes against 391 in our test), GET responses can be cached, every language has simple HTTP tools, and JSON is easy to read in a browser. There is no required contract file to generate first.
It is older and rarely chosen for new public APIs, but it is not gone. Plenty of live systems still publish WSDLs; we called one, the DNE Online calculator, on 4 October 2026 and got Add(2, 3) = 5.
Yes. REST does not fix a format. Most REST APIs use JSON because it is smaller and easier to work with, but XML, CSV or images are all allowed.
An XML document that describes a SOAP service: its operations, the exact type of every input and output, and the address to send calls to. Our tiny service's WSDL was 2,878 bytes; tools like zeep read it and build the calls for you.
From the System Design course, in the order we would read them.
Primary sources only: standards, vendor docs and our own runs. Each one shows its date and the day we opened it.
REST vs SOAP is one row in a much bigger table. Our System Design course has 770 lessons on networks, databases, caching, scaling, messaging, security and reliability, each drawn step by step, so you can explain the trade-off in an interview and pick right at work. 18 lessons are free to read, with no card needed.
the hands-on parts are real runs, like this one
course 1
From absolute beginner to principal engineer, drawn step by step.