REST vs SOAP — what nobody told me when I started working with both

REST and SOAP are both ways of sending and receiving data between systems. They do the same job. They just do it very differently. And nobody really explained that to me clearly when I started. I just kept looking for patterns until things clicked.

This is what I wish someone had said out loud.

How I actually encountered both

I use REST most of the time. It feels natural at this point. I think in it, I debug in it, it's the default mode.

Then a client comes along running Adobe Campaign Classic and suddenly I am looking at XML wrapped in envelopes and thinking okay, different rules here. SOAP shows up with older enterprise systems a lot. The kind of platforms that were built before REST was even a thing and have no intention of changing now.

You don't always get to choose which one you work with. The system chooses for you. So you learn to read both.

My approach when I hit something unfamiliar is always the same, look for the patterns. What is this sending? What structure is it expecting back? What breaks when something goes wrong? The specifics change but the thinking doesn't.

What REST actually is

REST stands for Representational State Transfer. It is an architectural style for building APIs that communicate over HTTP. It sends and receives data in JSON format, which is lightweight, human readable, and maps naturally to JavaScript objects.

It works with standard HTTP methods: GET to retrieve data, POST to send it, PUT to update it, DELETE to remove it. If you have done any web development you already know these.

javascript// GET request — retrieving a user
const response = await fetch('https://api.example.com/users/1', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

// POST request — creating a user
const newUser = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Shan',
    role: 'Integration Developer'
  })
});

const result = await newUser.json();
console.log(result);

Clean. Readable. Does exactly what it looks like it does.

What SOAP actually is

SOAP stands for Simple Object Access Protocol. The word simple is doing a lot of heavy lifting there.

SOAP sends data wrapped in XML inside a defined envelope structure. It has strict rules about how messages are formatted, what headers look like, and how errors are handled. It was built for enterprise environments where consistency and security matter more than convenience.

xml<!-- SOAP request envelope -->
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader>
      <Username>shannon</Username>
      <Password>supersecure</Password>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <GetUser>
      <UserId>1</UserId>
    </GetUser>
  </soap:Body>
</soap:Envelope>

<!-- SOAP response -->
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetUserResponse>
      <Name>Shannon</Name>
      <Role>Integration Developer</Role>
    </GetUserResponse>
  </soap:Body>
</soap:Envelope>

More verbose. More rigid. But when you are working with systems like Adobe Campaign or banking platforms or healthcare integrations, this is the language they speak and you meet them where they are.

The practical differences side by side

Data format: REST uses JSON, SOAP uses XML.
Protocol: REST works over standard HTTP, SOAP has its own protocol on top of HTTP.
Flexibility: REST is flexible about structure, SOAP enforces a strict contract.
Error handling: REST uses HTTP status codes like 404 or 500, SOAP has its own fault elements inside the envelope.
When you see it: REST is everywhere in modern APIs and web services. SOAP shows up in enterprise systems, legacy platforms, and anywhere that was built before REST became the standard.

How I approach switching between them

When I hit a new integration I look for patterns first. What format is the data in? What does the request structure look like? What does a successful response look like versus an error?

With REST that usually means checking the endpoint documentation and looking at the JSON structure. With SOAP it means finding the WSDL file which defines all the operations and data types the service supports, and then working out what envelope structure it expects.

The thinking is the same. The syntax is just very different.

The one line to remember

REST is a conversation. SOAP is a legal contract.

Both get the job done. One just requires a lot more paperwork. And sometimes the paperwork is not optional.

推荐订阅源