REST Architecture in Detail (With one thing no one knows)

REST API Architecture logo

Updated on December 3, 2019 at 8:35 am by Mehmet Egemen Albayrak

REST stands for Representational State Transfer – don’t worry, I will teach you each term in a very clear way -. I am sure you heard “RESTful API” term before and are acquainted with REST architecture and applications.

As can be seen in usage, REST is an architectural style for constructing Web Services(WS – This abbreviation is important for understanding other components of other Web Services like “Web Services Definition Language[WSDL]” of SOAP for example. REST Web Services is abbreviated as “RWS”) over HTTP – recently over TLS and SSL.

What does REST over HTTP means?

HTTP is an application layer(layer 7) protocol in OSI(You should definitely learn it from here). You may be confused about what is protocol and what is the protocol of an application, I happily will try to explain everything to you as clear as I can.

We should look at the protocol’s definition in the dictionary:

[mass noun] The official procedure or system of rules governing affairs of state or diplomatic occasions.

Simply an application protocol means an agreed way of speaking between applications. In our case, we use a browser as a client which sends HTTP requests.

GET /index.php HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Connection: Keep-Alive

This is what our browser sends to a server, in this case to this blog. GET is one of the safe HTTP Verbs(we will learn what that means). When we make our request in this special way of speaking to a server, the server responds with a response us to parse it.

HTTP/1.1 404 Not Found
Date: Tue, 23 Jul 2019 16:21:50 GMT
Server: Apache/2.2.14 (Win32)
Content-Length: 233
Connection: Closed
Content-Type: text/html; charset=iso-8859-1
   <title>404 Not Found</title>
   <h1>Not Found</h1>
   <p>The requested URL /index.php was not found on this server.</p>

Server says to us that there is no such a page or in REST language “resource not found” and sends us an error page as a payload which browser to parse and show it to you.

This is an example of communication between a server and a client. You can see the capabilities and more of the HTTP protocol in RFC 2616, it’s basically everything about HTTP.

What is that “GET” in the request?

As I mentioned at the beginning of the post GET is a safe(safe because it doesn’t change anything) HTTP Verb and it gets the representation of the resource from an URL or URI. There are several HTTP Verbs, each cause different things to happen. Essential 4 HTTP Verbs are

  • GET
  • POST
  • PUT

There are 39 HTTP Verbs in total; like HEAD, MERGE, PATCH, etc. You can see all verbs and read their corresponding RFCs to learn more here.

What is “404 Not Found”?

404 is an HTTP status code. There are different codes starting with 1xx, 2xx, 3xx, 4xx and 5xx. For example, codes start with 2 indicates success, whereas codes start with 4, indicates an error. You can read what every code means here.

404 means resource not found, which brings a question…

What is a resource?

In the old days of the internet, a resource was just a document or a file in the REST architecture. Now it can be also images, videos, audio files, etc.

Another resource can be a record from the database. In REST Architecture representation of resources are served. For example when you make a request to GET a database record from the server(usually frontend application you use makes this request with packages like “Axios”)

GET /users/mehmetegemen HTTP/1.1
User-Agent: Mehmet Egemens Browser/1.0
Accept-Language: en-us
Accept-Encoding: gzip, deflate

to get this database record from, let’s say, your MongoDB instance:

  "_id": ObjectId("54759eb3c090d83494e2d804"),
  "username": "mehmetegemen",
  "password": "$2b$10$3euPoxWFCibloSdCY2s1l.56VLtr4QsXb6feBdZ0m/3pd/lhw",
  "role": "admin",
  "userId": 1

our resource contains sensitive information but we are lucky, in REST architecture responses are representations of resources. We can mold the representation.

You interact with representations, not resources itself.

We get this response from the server:

HTTP/1.1 200 OK
Date: Tue, 23 Jul 2019 18:48:37 GMT
Server: Apache/2.2.14 (Win32)
Content-Length: 60
Content-Type: application/json;

  "username": "mehmetegemen",
  "role": "admin",
  "userId": 1

Two little details which other blog posts don’t give; a request body sent from a browser is also a representation.

And In REST Architecture resource is a conceptual entity or entities which may be subjected to a change by time, or not. Not just a document or file, anything can be targeted is a resource.

Above response looks like it contains an ordinary JSON document, though, there must have some constraints which makes REST architecture an architecture thus its response.

What are the constraints of REST architecture?

In REST architecture there are some points which define our operations, otherwise, we aren’t doing REST. In the original work of Roy Fielding, constraints are very very detailed.

To make our API REST compatible we should take followings to account:

Client-Server Architecture

In a REST compatible system client and the server must be loosely coupled. A change in the server should not affect the client and vice versa. We will see how to achieve that in HATEOAS section.

Stateless Communication

When connected to server your connection can get a state and get saved in the system, like a “connecting” state changes to “established” state and application can remember this. In REST every connection has to be stateless thus have to have all the necessary information in the HTTP request or response.

By adhering to stateless communication style, we increase visibility, reliability, and scalability of our system.  They increase because one request with every detail is enough for one response. You can see all properties can be improved here.


In Mr.Roy’s work, the term “client-cache-stateless-server” is used. It’s like an acronym, defines how the client and server should be.

In REST architecture a server response must contain that the response can be cached or not in the header.

Layered System

A layered system’s layers use the service below it to provide it to service above. They can service with specific roles or they can be proxy services just forwarding requests to the next layer.

The layered system comes with its disadvantages. More layers introduce more delay in the system which can be perceived by the user. The advantage is increased evolvability and reusability.

Uniform Interface

It’s basically encapsulating a service in a standardized way. All REST web services must be built on these principles:

  • Identification of Resources
  • Manipulation of resources through representations
  • Self-descriptive messages
  • Hypermedia as the engine of application state

Additional optional principles:

  • Code-on-demand
  • Supply for intermediaries

I never let you alone with cryptic and esoteric terms so let’s learn these.

Identification of Resources

A URI(Uniform Resource Identifier) identifies a resource as its name implies. A URI example points to a database record of the 12th post. But it could be a conceptual entity too, like “funny dinosaur meme” at

Manipulation of Resources Through Representations

Do you remember that I said what also sent by the client(browser in that example) is a representation? Imagine a browser sends a JSON document to be saved into the database on the server or sends an image to an Amazon S3 Bucket.

But if we send the document or the file to a resource path(the /memes/dinosaur after is a resource path), how will we tell essential information to the server? As I mentioned before, every request has a header.

Two of the most important information in the header are Accept and Content-Type fields. Accept tells what media-type requester will accept in return to a response with a specific Content-Type(for example application/json). Media-types for the content-type field can be found here.

POST /shoes HTTP/1.1

Accept: text/plain
Content-Type: application/json

  "sendMeText": true
HTTP/1.1 200 OK



You can read the RFC about Accept header here, and Content-Type here.

Self-Descriptive Messages

We said a request to a REST endpoint must have all the required information in it because of statelessness. Having fields like Accept, Content-Type, User-Agent, Host, etc. in the header and having a body makes a message self-descriptive.

Roy Fielding emphasizes a lot how HTTP/1.0 failed at being self-descriptive with much details at section 6.3.2 of his doctoral dissertation.

Support Intermediaries

As I mentioned in the Layered System section there can be proxies between services. These proxies or in other words intermediaries can have additional properties like caching or firewall.


A REST API can send anything, including a portion of a script. This script can be executed on the client.

Hypermedia as the Engine of Application State – HATEOAS

What is Hypermedia?

Wikipedia says:

Hypermedia, an extension of the term hypertext, is a nonlinear medium of information that includes graphics, audio, video, plain text and hyperlinks.

The WWW (World Wide Web) is a classic example of hypermedia, whereas a non-interactive cinema presentation is an example of standard multimedia due to the absence of hyperlinks.

To understand hypermedia better let’s see what is hypertext:

Hypertext is text which is not constrained to be linear.

Hypertext is text which contains links to other texts.

Basically, hypermedia is something has graphics, videos, audios, texts, etc. which lets you visit other pages in your preference a.k.a. non-linearly, not sequentially.

Hypermedia in HATEOAS context means you can know where to visit next from the response you’ve acquired.


I didn’t know anything called HATEOAS and made APIs according to express.js functions instead of molding it by specifications. The first time I heard of HATEOAS was the time that I wrote a REST vs SOAP(I wrote it long before publishing on Medium) survey. And I realized I was doing the API design wrong, or with better words, incomplete.

HATEOAS aims for the user to explore a REST API from the responses he got from the server. A HATEOAS compatible response body would be like

  "type": "object",
  "title": "Some Post Title",
  "content": "... HUNDREDS_OF_PARAGRAPHS ...",
  "links": [{
    "rel": "self",
    "href": "posts/{slug}"
    "rel": "author",
    "href": "posts/{slug}/author"

This is JSON Schema and its hyper-schema standard. I just wanted to show you links array populated with possible routes. By doing this a user can explore your API like an HTML page. But I want to show you how to implement it along with the definition.

One of the simplest HATEOAS specifications of JSON documents is HAL. It’s really easy to implement in Node.js(I use it) thanks to the open-source hal library. A code like this(in Express.js):

const hal = require("hal");

const identityInfoCollection = new hal.Resource(
);"authentication", {
  href: "/identities/authentication",
  method: "POST",

res.set("Content-Type", "application/hal+json");
res.send(identityInfoCollection.toJSON(" "));

Results in this JSON response:

    "_links": {
        "self": {
            "href": "/identities"
        "authentication": {
            "href": "/identities/authentication",
            "method": "POST"
    "email": "[email protected]",
    "fullName": "Mehmet",
    "username": "fe",
    "geolocation": {
        "lat": 59.89161,
        "lon": 54.23223

As you see it’s important to set headers for Content-Type and Accept. After doing everything correctly, a client or an API consumer can know what’s the next stop after the response of his/her/its request. This simple thing is very rarely known because most of the developers are learning to code from Express.js tutorials and completely unaware of specification rules like HATEOAS, resources must be nouns or the correct verb for the request(knowing the difference between PUT and POST, etc.). Congrats, now you know a rare thing, keep up the good work(i.e. reading my blog).

I wrote this article because my next post will be about API specifications like HAL, JSON:API and JSON Schema’s hyper-media. If you want to ask something or just say your good wishes, don’t forget to comment. You can share the post with others if you think they will benefit. Also, you can subscribe by clicking here for more well-thought and unique content. I wish you a productive day.

Software Engineering HATEOASRESTREST API

2 thoughts on “REST Architecture in Detail (With one thing no one knows)

    1. Thanks! I will also write about GraphQL, you can subscribe if you want to learn a REST alternative.

Leave a Reply

Your email address will not be published. Required fields are marked *