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.

RESTful means that the API is based on HTTP and stateless principles.

HTTP has a lot of different methods to make a call to a server. For example, when opening a website, the browser uses GET to get a resource. You can use GET to fetch data. However, if you want to push data to the server, HTTP provides other methods, like POST and PUT, depending on what you want to do. You can even call a web address with DELETE to remove data. Those are the most important methods.

In order to use the methods, you will want to make AJAX calls in the browser, or use the NodeJS request API. Both of them take the method as a string-parameter at some point. For example:

// create async server request object
const xhr = new XMLHttpRequest();

// specify HTTP method and URL
xhr.open('POST', 'example.com/some/rest/api/node');

// specify timeout in ms
xhr.timeout = 3000;

// react to timeout
xhr.ontimeout = () => console.error('TIMEOUT!');

// react to error while trying to connect to server
xhr.onerror = console.error;

// react to state change, for example success :)
xhr.onload = function() {
    // only react to finished requests
    if (this.readyState === 4) {
        // if the server returned OK
        if (this.status >= 200 && this.status < 300) {
            // write response from server to console
            console.log('SUCCESS: ' + this.response.toString());

        // if the server returned ERROR
        } else if (this.status >= 400) {
            console.error('ERROR STATUS: ' + this.status.toString())
        }
    }
};

// finally, send the request. You can add data, if you want
xhr.send(JSON.stringify({ foo: 42, bar: 'Hello!' }));

The other thing, which is important for RESTful, is that the server does not store the client's state. The client will have to transmit everything the server needs to know in order to process a request on each and every request. That includes login information, tokens, data, etc. The server will do no magic and memorize anything for you. However, that should also be obvious from the documentation, which should include all the fields you have to send via the request.

REST is very useful, because it allows easy server-side logic and makes scaling a breeze, while still being super easy on the client side. Today, it still is the default way to build a stable web API, though some other strategies do exist.