What makes an API RESTful, and how is that different from SOAP?
REST is an architectural style, not a protocol. An API is “RESTful” when it treats everything as a resource identified by a URL, uses standard HTTP verbs to act on that resource (GET to read, POST to create, PUT/PATCH to update, DELETE to remove), is stateless (every request carries everything the server needs, the server holds no session state about the client between requests), and typically returns a representation of the resource, most often JSON.
How SOAP differs
SOAP is an actual protocol with a strict, verbose XML envelope for every message, and it usually relies on a WSDL contract that formally describes every operation, its inputs, and outputs, machine-readable and rigid by design. SOAP also has built-in standards for things REST leaves to convention: WS-Security for message-level encryption, WS-AtomicTransaction for distributed transactions. That rigidity is exactly why some enterprise, especially financial and government, systems still use it: the formal contract and built-in transactional guarantees matter more there than developer convenience.
Best practice for REST design
Model URLs around nouns, not verbs (/orders/123, not /getOrder?id=123), use HTTP status codes meaningfully (404 for not found, 409 for conflict, 422 for validation failure, not 200 with an error message buried in the body), version your API from day one (/v1/orders) since breaking changes are inevitable, and make endpoints idempotent where the HTTP spec expects it, PUT and DELETE should be safe to retry without side effects.
Edge case interviewers probe for
Ask what “stateless” actually rules out. It means the server can’t remember you between requests (no server-side session tied to a connection), but it doesn’t mean the server has no database, your auth token or session ID is passed on every single request precisely because the server isn’t tracking who you are in between.
Common mistake
Calling any API that returns JSON over HTTP “RESTful.” An API with /api/getUserData?action=delete using GET for a delete operation is JSON-over-HTTP, not REST, it violates both the resource/verb model and HTTP’s own semantics for what a GET should be allowed to do.
What the interviewer is checking
Whether you understand REST as a set of constraints with real reasons behind them, not just “an API that isn’t SOAP.”
Think of REST like ordering at a counter using plain, universal words everyone already knows: “get me the pizza,” “cancel my order,” “change my order to a large.” You don’t need a special manual to order, the actions (get, cancel, change) work the same way at every counter you visit.
SOAP is more like filling out a detailed, official government form for every single request, with a strict template that must be filled out exactly right, in a specific format, often notarized (signed and verified) before anyone will process it. Slower and more paperwork, but for something like a bank wire transfer, that rigid, verifiable paper trail is exactly the point.
“Stateless” just means the counter person has no memory of you from your last visit. Every single time, you have to say your full order again (or show your receipt/ID) instead of them recognizing you and knowing what you want. It sounds inconvenient, but it means any counter worker can serve you at any time, nobody has to specifically remember your history for the system to work.
Why interviewers ask this
API design is one of the most common day-to-day tasks for a backend developer, and sloppy REST design (verbs in URLs, wrong status codes, stateful assumptions) causes real integration bugs down the line.
What a strong answer signals
That you understand REST’s constraints as deliberate tradeoffs (simplicity and scalability over SOAP’s rigidity and built-in guarantees), not just “REST good, SOAP old.”
Common follow-ups
- What’s the difference between PUT and PATCH?
- How would you version a public API without breaking existing clients?
- Why does statelessness help an API scale horizontally?
Advanced variation
“Design the API for a hotel booking system,” which expects proper resource modeling (/hotels/:id/rooms/:id/bookings), correct status codes for a double-booking conflict (409), and a stance on idempotency for the booking creation endpoint.
A logistics client integration originally exposed /api/shipment?action=updateStatus accepting POST for every operation, with the actual intent buried in a request body field. Refactoring to proper REST, PATCH /shipments/:id with a JSON body describing just the changed fields, plus real status codes (404 for an unknown shipment ID, 409 if the requested status transition was invalid, like marking a cancelled shipment as delivered), let the partner’s client library use standard HTTP error handling instead of parsing custom error strings out of a 200 response, which had been silently swallowing failures for months.
# Read a resource
GET /v1/shipments/8842
-> 200 OK
# Partially update a resource; only changed fields in the body
PATCH /v1/shipments/8842
Content-Type: application/json
{ "status": "in_transit" }
-> 200 OK
# Invalid state transition -> meaningful status code, not 200
PATCH /v1/shipments/8842
Content-Type: application/json
{ "status": "delivered" }
-> 409 Conflict
{ "error": "cannot mark a cancelled shipment as delivered" }- 1REST is an architectural style built on resources, HTTP verbs, and statelessness, not a specific protocol.
- 2SOAP is a strict, XML-based protocol with a formal contract (WSDL) and built-in security/transaction standards.
- 3Model URLs as nouns and use HTTP verbs and status codes for their real, standard meaning.
- 4Statelessness means every request carries what the server needs; it doesn’t mean the server has no persistent data.
- 5SOAP still fits domains needing rigid contracts and built-in transactional guarantees, like some banking systems.