Ali Alp

Posted on Oct 8, 2019 • Edited on Mar 31, 2020

SOAP vs REST

#beginners #soap #restful #webdev

This article will demystify the enigma of SOAP or REST once for all. As a software developer I can remember the struggles which I have endured to understand the real story behind the SOAP and REST APIs and therefore in this article I will try to simplify them as much as possible. so, without any further ado let's dive in.

You can access all the sample codes here

SOAP

It stands for Simple Object Access Protocol but please forget the abbreviation and just learn it as SOAP like my name which is Ali , who knows maybe it stands for "Artificial Language Intelligence" :) , there was a time which SOAP abbreviation was making sense but maybe not anymore.

What is a Protocol

If I asked you

How are you?

How can I make sure that you will answer "fine”? no way right?

how about

2 + 2 =?

this time I can be quite sure that your answer is 4, right? because me as the writer and you as the reader both are using the same protocol which is mathematic. this is the definition of a protocol. SOAP is a protocol as well.

In SOAP protocol in order to call a function which is taking a name as its argument and response with a greeting message like this

Greeting: function(args) { 
    return {result: "Hello dear " + args.name};
}

We should ask it like this

SOAP Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header/>
  <soap:Body>
    <ns1:Greeting xmlns:ns1="urn:examples:GreetingService">
      <name>Ali Alp</name>
    </ns1:Greeting>
  </soap:Body>
</soap:Envelope>

and we will receive a response like this

SOAP Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header/>
  <soap:Body>
    <ns1:GreetingResponse xmlns:ns1="urn:examples:GreetingService">
      <result>Hello dear Ali Alp</result>
    </ns1:GreetingResponse>
  </soap:Body>
</soap:Envelope>

As it can be seen above, in order to call a simple Greeting service, there are a lot of meta data which needs to be transmitted, meanwhile the complexity of the SOAP is not ending here and there is one more piece which is required for the SOAP in order to function. WSDL or Web Service Description Language is a super complicated XML file which the SOAP web-service is using to explain its services to the clients, basically it's announcing the details of the SOAP envelope that you need to generate for your request.

Below you can find the WSDL of the greeting service which has been mentioned above

<definitions name = "GreetingService"
   targetNamespace = "http://www.examples.com/wsdl/GreetingService.wsdl"
   xmlns = "http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap = "http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns = "http://www.examples.com/wsdl/GreetingService.wsdl"
   xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
   <message name = "GreetingRequest">
      <part name = "userName" type = "xsd:string"/>
   </message>
   <message name = "GreetingResponse">
      <part name = "result" type = "xsd:string"/>
   </message>
   <portType name = "Greeting_PortType">
      <operation name = "Greeting">
         <input message = "tns:GreetingRequest"/>
         <output message = "tns:GreetingResponse"/>
      </operation>
   </portType>
   <binding name = "Greeting_Binding" type = "tns:Greeting_PortType">
      <soap:binding style = "rpc"
         transport = "http://schemas.xmlsoap.org/soap/http"/>
      <operation name = "Greeting">
         <soap:operation soapAction = "Greeting"/>
         <input>
            <soap:body encodingStyle = "http://schemas.xmlsoap.org/soap/encoding/" namespace = "urn:examples:GreetingService" use = "encoded"/>
         </input>
         <output>
            <soap:body encodingStyle = "http://schemas.xmlsoap.org/soap/encoding/" namespace = "urn:examples:GreetingService" use = "encoded"/>
         </output>
      </operation>
   </binding>
   <service name = "Greeting_Service">
      <documentation>WSDL File for GreetingService</documentation>
      <port binding = "tns:Greeting_Binding" name = "Greeting_Port">
         <soap:address
            location = "http://www.examples.com/Greeting/" />
      </port>
   </service>
</definitions>

As it can be seen it is a complicated XML code for a simple service, but considering the interoperability of it, will justify its complexity, moreover there are plenty of tools out there to generate WSDL for you.

Pros

WS-Security (custom security implementation support)
WS-AtomicTransaction
WS-ReliableMessaging
Language, platform, and transport independent
Works well in distributed enterprise environments
Standardized
Provides significant pre-build extensibility in the form of the WS standards
Built-in error handling
Automation when used with certain language products

Cons

High bandwidth usage
Complex to learn
heavy to parse and process
only support XML

REST

REST stands for "Representational State Transfer". If you figured out the SOAP therefore understanding REST will be piece of cake.

REST is not a protocol like SOAP, and also it has been designed to work over the HTTP protocol while SOAP is independent of any language, platform and transport.

In REST in order to call a function which is taking a name as its argument and response with a greeting message like this

Greeting: function(args) { 
    return {result: "Hello dear " + args.name};
}

We should ask it like this

http://server:port/greeting?name=Ali-Alp

and we will receive a response like this

Hello dear Ali-Alp

Pros

No expensive tools require to interact with the Web service
Easy to learn
Efficient bandwidth usage (Smaller message size comparing to SOAP)
Fast (no extensive processing required)
Closer to other Web technologies in design philosophy

Cons

Not very secure
External documentation of the data model is required

I hope you have a better understanding of both SOAP and REST API, to answer the enigma I should say that there is no enigma in the first place. maybe both SOAP and REST are being used in same direction, but they are totally for different applications. A rule of thumb use REST for most of your web-services and in case you really stuck with the available features of the REST API and you did your research enough then have a look at the SOAP protocol.

You can access all the sample codes here

Top comments (13)

Thorsten Hirsch • Oct 9 '19

I think it's good to know where SOAP comes from in order to understand why it's so complicated. In the days when SOAP was born, there was no REST. And there were no SPAs. Frontend developers were not the people SOAP was made for. Instead it was made for backend developers. SOAP was made for asynchronous message communication between your enterprise services.

The good thing about SOAP is that it's a widely adopted standard for backend services. But it was made to be a solution for each and every problem, everything was put into the message, the service description (WSDL) contains a schema for validating the XML messages, and even security (WS Security) is part of SOAP (no, that's definitely not a "Pro" point, Ali)! Nowadays everybody knows that separating concerns is the way to go, and moving security into the transport layer (SSL) is one of the reasons why REST is so simple.

Ali Alp • Oct 9 '19

That's right , indeed the WS-Security is part of SOAP, but i have mentioned it as its Pros because of the flexibility and the fact that you can implement your custom security needs while in SSL you need to follow the protocol , but of course you need to consider the cost of the performance and bandwidth.
Good point though :) therefore i have edited the text

Thorsten Hirsch • Oct 9 '19

Thank you, Ali. At least they didn't make WS-Security mandatory in SOAP, so you're free to do security in the transport layer when using SOAP.

metz2000 • Oct 14 '19

WS security is way more than TLS. It covers integrity, confidentiality (encryption) and identity verification, and does it in a protocol agnostic way. Second point can be achieved with HTTPS on protocols where available, the others are not covered by TLS. Also in some cases it is redundant to encrypt the full message, only parts need encryption and this reduces overhead. Ie internal services often communicate over http to not have the overhead of https but some parts of some messages may need encryption and WS security provides an off the shelve solution. Yes these come with a cost but so does TLS.

TuWang • Oct 9 '19

maybe it’s worth to mention RPC, and graphql to completely blows up reader’s mind ;)

Dmitry Lukanin • Oct 9 '19 • Edited

Well, SOAP is RPC realisation. :) But yes, IMO it's better to compare SOAP and other RPC's (like JSON RPC or GRPC), than comparing it to REST.

Davmi Jose Valdez Ogando • Oct 8 '19

I've always felt that SOAP should be mostly used for business communication, since you need some sort of contract done for each application consuming your endpoints, whenever REST covers anything else out of that scope.

Max Ong Zong Bao • Oct 9 '19

Wow, there are people who still use SOAP I thought that everyone is moving towards REST.

Anyway, I do agree that it should be compared to other protocols like GRPC or GraphQL to be that extensive which API Evangelist has done a good job for it.

Evie • Oct 10 '19

Love the way you've explained what a protocol is. I'm definitely going to pinch that!

Kiss, György • Oct 10 '19

Not sure if you are just trolling or you are just ignorant or what happened to you, but SOAP is the worst protocol ever and your counterpoints against REST are bogus.