SOAP

Definition

Before REST dominated the API landscape, SOAP (Simple Object Access Protocol) was the standard way for enterprise systems to communicate. It is a protocol built on XML that defines exactly how to structure messages, handle errors, and implement security. Despite the word “Simple” in its name, SOAP is actually quite complex - but that complexity enables features that simpler protocols lack.

SOAP takes a different philosophy than REST. While REST is flexible and lets developers make many choices, SOAP is prescriptive - it tells you exactly how everything should work. Every SOAP message has an envelope structure with a header (for metadata like authentication) and a body (for the actual data). Error handling follows a specific format. Security can be built into the message itself, not just the transport. This rigidity is both SOAP’s strength and its weakness.

For enterprise systems that need formal contracts, transaction support, and advanced security, SOAP remains relevant. Banks, healthcare systems, and government agencies often require the features SOAP provides: message-level encryption (not just transport-level), digital signatures on individual elements, reliable delivery guarantees, and formal service contracts. When you absolutely need these guarantees, SOAP delivers - but you pay in complexity and verbosity.

Example

Airline reservation systems: Global Distribution Systems (GDS) that power airline bookings use SOAP. When you search for flights on Expedia, there is a good chance SOAP messages are flying between systems to check availability and prices.

Payment gateways: Many enterprise payment systems use SOAP for card processing. The strict contracts and security features help protect financial data and ensure compliance with PCI-DSS requirements.

Healthcare interoperability: HL7 and other healthcare standards often use SOAP for exchanging patient records. The ability to sign individual message elements helps meet HIPAA requirements.

Enterprise service buses: Large organizations use SOAP services as the backbone of their integration architecture. SAP, Oracle, and Microsoft systems commonly expose SOAP interfaces.

Analogy

The Registered Legal Letter: SOAP is like sending a registered letter through a law firm. There is a formal envelope with specific sections for addresses and contents. You get proof of delivery, signature verification, and tamper-evident seals. It is more work than a casual email, but when the stakes are high, you want those guarantees.

The Diplomatic Pouch: International diplomats send sensitive documents in diplomatic pouches with specific protocols: sealed, documented chain of custody, tamper-evident packaging. SOAP’s WS-Security features provide similar protections for digital messages.

The Medical Chart: A patient’s medical chart follows a specific format that every doctor understands. There are designated sections for history, vitals, medications, and notes. SOAP messages have a similarly rigid structure that ensures everyone interprets them the same way.

The Legal Contract: A legal contract has specific required sections: parties involved, terms, signatures, dates. You cannot just write a contract any way you want - it must follow certain conventions to be legally binding. SOAP enforces similar conventions for API messages.

Code Example

<!-- SOAP Request -->
POST /api/soap [HTTP/1.1](https://reference.apios.info/terms/http-1-1/)
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
    <auth:Token>abc123</auth:Token>
  </soap:Header>
  <soap:Body>
    <m:GetUserRequest xmlns:m="http://example.com/users">
      <m:UserId>123</m:UserId>
    </m:GetUserRequest>
  </soap:Body>
</soap:Envelope>

<!-- SOAP Response -->
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <m:GetUserResponse xmlns:m="http://example.com/users">
      <m:User>
        <m:Id>123</m:Id>
        <m:Name>Alice</m:Name>
      </m:User>
    </m:GetUserResponse>
  </soap:Body>
</soap:Envelope>

Security Notes

Standards & RFCs