REST API

REST API’s

You see this term all over the place, along with “RESTful API’s”. You might think REST is an actual program, perhaps an NPM package you can download. I probably did when I first started. I had a decent understanding of the concept, or thought I did, until an interview question took me for a loop. Turns out my understand of REST was not so hot.

REST stands for REpresentational State Transfer. Look at that, they even decided to use the first two letters of the first word, I guess REST sounds cooler than RST. Pretty sure there are rules against this type of acronym creation, and if not there should be! REST is not a programming language, NPM package, or a protocol. It is an architectural style outlined in by someone called Roy Fielding for his dissertation way back in the year 2000. Here is a link to the actual paper, if you want to see for yourself.

REST just outlines a style for computers using the client-server model to communicate, best practices, if you will. Dr. Fielding outlined six things required by an API to it a REST API:

  • Client-Server

    Stateless

    Cache

    Uniform Interface

    Layered System

    Code On Demand

If you your architecture meets this six constraints then it will have desirable properties such as decoupling, simplicity, scalability. These six are collectively called REST.

1. Client Server

A REST API must use the client-server model, one computer acts as the client and sends requests to the other computer, acting as the server. Different from a peer-to-peer model, in which the client could also act as server and respond to requests, and vice versa. The client-server model works well for this, the client is the one requesting something, and does not share any of it’s resources, and does not take random requests from others. In the case of the REST API, it allows you to change your client side code without worrying about the server code, you know what kind of response you will get. The same for the server side, you should be able to modifying the database (such as add users to the user object) without the client being impacted (or ever even knowing, if wanted). Now both the client and server can scale independently of each other.

2. Stateless

REST is stateless, which means the client passes all the details to the server that is required to perform the action. What? In this case, stateful means that the server would store information about the client and use that information over a series of requests. So, one request might be dependent on the state of a previous request. SOAP can also be stateless. REST, however, means it is required that the server stores no information about the client, all the data needed for the server to provide it’s service/data/function to the client will be provided by the client in the call.

3. Cache

REST requires the use of cache. Data within a response to a client request should be labeled as cacheable or non-cacheable, this is to improve speeds and so less data is sent. Saves trips! Uses less energy! No dolphins killed! Honestly, is there a downside???

4. Uniform Interface

“The key to the decoupling client from server is having a uniform interface that allows independent evolution of the application without having the application’s services, models, or actions tightly coupled to the API layer itself.” -source

Basically lets the the client and server talk to each other in a single language, when on the backend they might both use different languages.

This one is a bit complicated. It has four sub constraints that must be met:

  1. Identification of resources: In REST, a resource could be anything. User info, an image, an HTML document. Each resource must be uniquely identified, that does not change. The resource identifier should not change, even when the resource information does change/modified. If the resource is no longer there, the server should be able to give the client a response telling it so.

    The internet uses URI’s Uniform Resource Locators to identify resources, along with HTTP to communicate to them. REST almost always also uses URI’s to identify resources.

    1. Manipulation of resources through representations: This one is super cool. Basically the server has control over the resources. If the client wants to modify a resource, the client needs to send the server a representation of what it wants that resources to look like. For example, a non REST API might send the server instructions saying something like “Make the first letter of each word capital” in code. A REST API would simply send an object representing what it wants, in this case the text with each letter already capitalized. REST just sends out what it wants the final version to look like, awesome!
    2. Self-descriptive messages: Easy, the message must contain all the information needed to understand it. No additional message needed to be sent. Not sending a message, and another message with information on how to decode the first message.
    3. Hypermedia: Sounds really advanced!!! Turns out it is just a fancy word meaning data sent from the the server to the client which contains information about actions the client is now allowed to take. HTML is a form of hypermedia the server can sent back to a client. How so? Because the HTML might contain links telling the client actions it can take, meaning “click this link to go to this address”. That is an action the client could take. An image tag would tell the client to immediately send a GET request to the URL with the image source added to the end. 
  2. <a href= “http://www.dodgeviper.com”> Wow so fast, much power </a>

<img src="1997gts.jpg">

That’s it for Uniform Interface! Now back to the main list.

5. Layered System

Basically, there can be more to the system than just clients and servers, other layers of things like an onion. REST allows this, but each layer is only aware of the next layer, and that is all the interact with. A proxy that forwards HTTP requests is an example of a layer.

6. Code on Demand

Ever heard of an “optional constraint”? Well, now you have! This seems like one of those annoying trick interview questions. REST API’s have to meet how many constraints? Six? No, there are five, one is optional. Alternatively, if I said “five” I am sure they would come back and tell me it was six. You just can’t win, I’m telling you. Apparently code on demand just means the server can send executable code to the client. An HTML