Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท REST vs SOAP

Choosing Between SOAP, REST, gRPC and GraphQL

A practical decision guide for picking SOAP, REST, gRPC or GraphQL - the questions to ask, the trade-offs, and a small Node.js scorer that turns requirements into a recommendation.

There is no "best" web service style, only a best fit for a situation. Teams get into trouble when they pick a style because it is fashionable, or because it is the only one they know, and then spend years working around it. A better habit is to write down the requirements first and let them point to an answer.

In this lesson you will meet the four styles you will meet most often (SOAP, REST, gRPC and GraphQL), learn the questions that separate them, and finish with a tiny scoring tool you can adapt for your own projects.

The four styles in one paragraph each

SOAP exchanges XML envelopes described by a WSDL contract. It shines in enterprise settings: formal contracts, WS-Security, WS-ReliableMessaging, WS-AtomicTransaction, and a long history in banking, insurance, telecom and government systems.

REST exposes resources at URLs and uses HTTP verbs and status codes. It is the default for public APIs because any HTTP client works, responses can be cached, and the learning curve is gentle.

gRPC uses Protocol Buffers over HTTP/2. Calls are compact binary messages with generated clients and server streaming. It is excellent for service-to-service traffic inside a data center, and weaker in browsers, which need a proxy layer.

GraphQL gives clients a single endpoint and a query language to ask for exactly the fields they need. It fits front-ends that aggregate data from many back-end sources, at the price of more complex caching and server-side query protection.

Pick by the problem

SOAP Formal contracts and WS-* security
REST Public, cacheable, simple clients
gRPC Fast internal service calls
GraphQL Flexible queries for UIs

Most companies run more than one.

1 / 2

Questions that decide it

Ask these in order. Each one removes options.

  1. Who are the consumers? Public developers and browsers favor REST. A handful of known partners with strict compliance rules may favor SOAP. Other microservices favor gRPC.
  2. Do you need a formal, machine-checked contract? SOAP (WSDL + XSD) and gRPC (.proto) give you one by default. REST needs OpenAPI added on top.
  3. Which non-functional features are required? Message-level signing and encryption that survives intermediaries, reliable delivery, or distributed transactions point to SOAP's WS-* family. Transport-level TLS is enough for most REST APIs.
  4. What is the transport? SOAP can run over HTTP, SMTP or JMS. REST needs HTTP. gRPC needs HTTP/2.
  5. How does data get consumed? Many small, cacheable reads suit REST. Complex nested reads shaped by each screen suit GraphQL.
  6. What already exists? If the partner's system exposes a WSDL, you are consuming SOAP whether you like it or not. Integration constraints often beat design preferences.

A scoring helper

The program below encodes those questions as weights. It is deliberately simple (real decisions need judgment), but writing the rules out makes your assumptions visible and discussable.

Node.js Requirements in, recommendation out

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Change the weights and watch the ranking move. If a single weight flips the answer, that is a sign the decision is genuinely close and other factors (team skills, existing tooling) should decide.

Same call, four shapes

Seeing the same request in each style makes the trade-offs concrete. Here it is as data we can print, with byte counts for the request body.

Node.js One request in four styles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The gRPC line is a description, because protobuf bytes are not readable text. The rest are exactly what a client would send.

Mixing styles on purpose

Real systems rarely pick one. A common architecture exposes REST or GraphQL to the outside, uses gRPC between internal services, and keeps SOAP adapters at the edge for partners who need them. The migration lessons later in this chapter family show how to place a REST facade in front of a SOAP back end, so the outside world sees a modern API while the proven system keeps working.

When in doubt, start with the style your consumers already know. A technically perfect API nobody can call is worse than an ordinary one they can.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A partner bank requires signed, encrypted messages that stay protected through intermediaries. Which style fits best?

    WS-Security protects the message itself, not just the connection, which is what intermediaries require.
  2. 2. A public API must be callable from any browser and have cacheable reads. Which fits best?

    REST uses plain HTTP GETs on URLs, which browsers and CDNs understand directly.
  3. 3. What is GraphQL's main advantage for front-ends?

    A query names the fields it needs, which avoids over-fetching and many round trips.
  4. 4. Which is the best reason a team ends up consuming SOAP in a new project?

    Integration constraints often decide: you adapt to the interface your partner already publishes.

Summary

  • Choose a style from requirements: consumers, contract, security, transport, data access pattern and existing systems.
  • SOAP fits formal enterprise contracts and WS-* features; REST fits public, cacheable APIs; gRPC fits fast internal calls; GraphQL fits flexible front-end queries.
  • Writing requirements as weights makes a decision explicit and reviewable.
  • Most real architectures combine several styles, with adapters between them.

Next: SOAP Faults vs HTTP Error Handling