Problem I have:
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.
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
Usersresource and wanted to access theuserwith theuser_uuidof123, 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:
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
GETall the resources, or if you wantDELETEall the resources, you use the/<Resource Name>route without an ID meaning that you want to performVERBon every possible resource.The metadata is ported to the
Headersfield (most of it, if not all) and additional options are provided as querystrings.Continuing with our
Userresource, we'd access it by sending aPOSTrequest to theURL:/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:
Along with some other security features.
Footnotes
In HTTP, there is a response code
418which 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
jarfile 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.