Comment by Shreyansh Pandey on "What is Restful web service and in what context do we use this?"

Let me tell you a story: of sadness, despair, and worst of all: XML.

Enter SOAP

Before the advent of REST, whenever someone wrote an API, it followed the simple principles of SOAP or Simple Object Access Protocol. As is evident by the name, SOAP is a fully fledged protocol by W3C.

I wouldn't go into the exact details of how SOAP was used, but very simple, you had an XML formatted request envelope which contained information about the resource you were accessing. This meant stuff like your authorization tokens, your authentication scopes, roles, identifiers, etc. All of this added a lot of extra to the request and hence, increased the usage of bandwidth. One place I will give SOAP the credit it deserves is that it is extremely reliable since it is ACID) compliant, you didn't have to worry about the kind of data it was returning.

As an example, suppose you had the Users resource and wanted to access the user with the user_uuid of 123, this is how you'd format the SOAP envelope:

POST /User HTTP/1.1
Host: www.api.myapp.io
Content-Type: application/soap+xml; charset=utf-8
Content-Length: xxx

<?xml version="1.0"?>

<soap:Envelope xmlns:soap="w3.org/2003/05/soap-envelope">

<soap:Body xmlns:m="example.org/stock">
  <m:GetUserByUUID>
    <m:UserUUID>123</m:StockName>
  </m:GetUserByUUID>
</soap:Body>

</soap:Envelope>

As you can already see that it is very verbose; and worst of all, it only understood XML. Now, I am not saying that the verbosity if bad (as we will see later), but for simple requests like these, it's redundant.

If I had to summarize SOAP in just a single line, it would be this:

SOAP offered data in the form of a function (like GetUserByUUID).

And thus, by extension, caching objects was a huge pain since SOAP was based on functions which accessed data.

Then there was light

Fed up with the verbosity and the extreme latency of servers serving SOAP, Roy T. Fielding laid out the principles of REST or Representational State Transfer.

You are free to read the paper, but the basic idea was this: RFC 7231 - a very fancy way of saying - introduced an idea of "verbs." These semantic building blocks along with a well defined status code was more than enough to build APIs with minimal overhead. Since this is baked into the protocol itself, there was no need to rely on third-party XML parsers and whatnot.

In general, we have the following verbs:

GET - get the resource;
POST - create the resource;
PUT - update the resource;
DELETE - delete the resource.

This combined with some good status codes like:

200 - OK;
201 - Created;
418 - I am a teapot (*)

meant that the API was fundamentally accessible, and self-documenting. Further, REST relies on the principle that the data is exposed as a resource instead of a function (like SOAP) and the HTTP verbs define which action should be performed.

The usual URL scheme followed is this:

<TLD>/api/<Version>/<Resource Name>/(<ID>?) (this is the URI or the Universal Resource Identifier)

When you want to GET all the resources, or if you want DELETE all the resources, you use the /<Resource Name> route without an ID meaning that you want to perform VERB on every possible resource.

The metadata is ported to the Headers field (most of it, if not all) and additional options are provided as querystrings.

Continuing with our User resource, we'd access it by sending a POST request to the URL: /api/v1/users/123. That is it. Just a simple request. No complicated request envelopes, no additional data parsing, etc.

Since all the data needed required to perform some action is sent in the request, REST is often deemed to be state-less (the reason why I say "often" is because you can have a stateless endpoint for a stateful operation: which is a bad practice)

Fine Print

Now, let's come to where SOAP is used vs. where REST is used.

You have used both of them - I am pretty sure - everyday. Whenever you go on Amazon.com and you see a list of the objects, it's done by sending a GET request to their API and the dataset is pulled, parsed and displayed (rendered). So, a RESTful API.

Now, when you click on Pay Now, you enter your card details which are then send (through a secure channel) to their payment processor (not the gateway; the gateway is the place where you - more or less - enter your card information.)

The payment processor, in turn, send a SOAP request for Authorization, Charge and Settlement. The reason why SOAP is used here is because:

you don't need caching since every request has to return new data and auth codes with object identifiers are a violation of the PCI/PA-DSS;
you need strong ACID compliance to make sure the data is not corrupted in-transit or in-process.

Along with some other security features.

Footnotes

In HTTP, there is a response code 418 which means "I am a teapot." Some of the most brilliant engineers, network designers and pioneers in the field actually decided to write an entire specification on this topic. You can read it up here. It was a light-hearted April Fool's day joke. However, in 2014 (exactly 16 years after the first release), RFC 7168 superseded the protocol which extend it by adding how a network tea-pot should make tea. It's a really funny documentation but even then, the semantics, working, and documentation is like any other actual RFC. Browse through it if you want something light!

In the past, I have worked on PCI-DSS compliant infrastructures and trust me when I say this: they are a pain. Primarily because every payment processor I have worked with comes as a jar file and requires a very strict deployment environment (for security); this makes the interoperability of the infrastructure a pain.

I hope all of this made sense! If you need help with anything in the text, drop a comment.

Overall my personal opinion is that REST introduced important concepts, but also took some steps back...

Yeah, I would say so too.

This is the data-format equivalent of static typing... Absolutely! (ACID)

I wouldn't say SOAP prevents one from enforcing statelessness; you can have a highly-decoupled, state-less web service with SOAP but that isn't what it should be used for.

Verbosity becomes an important factor when you are streaming all of this through a UDP layer (REST doesn't support this properly). The more packets you have, higher is the chance of in-transit corruption. I agree that there are workarounds for this problem (like a BER/DER encoded stream, etc.) but just on the surface.

In extension to the above, parsers do play an important role. JSON, by its very design, is light-weight and so are the parsers (some pretty inefficient ones as well :P). However, JSON doesn't (usually) follow a schema so validation and other such semantic verifications and validations thereof are not required. JSON has, what I would call, "best-practices" but no stone cold schema designs or definitions and even if they exist, no one really bothers to use it. However, with XML, this isn't the case as you are already aware. When we multiplex these requests over, say a NAT, the latency added by the parsers becomes a huge concern.

I am not talking about the deliberate delayed response mechanism, but the time required in parsing and validation.

Most of the opinions I have had with SOAP and XML stem from the payment industry. There, everything is mission critical, so we have to very closely instrument the code written.

Not to digress, but there was this company I worked for which had the most bizarre XSD in the world for a SOAP service. It took us 3 weeks to port all of that to Oracle compliant objects.

Search Hashnode

Enter SOAP

Then there was light

Fine Print

Footnotes