Gregor Riegler

About Gregor Riegler

Gregor is a passionate software engineer and RESTafarian who loves to continuously improve. He is interested in modern web development, oo-design and extreme programming. He is also serious about clean code and TDD.

Why REST is so important

This post is dedicated to REST, an architectural style of shaping webservices and the most misunderstood concept in the history of IT. This post is addressed to you who is designing webservice apis not being fully aware what REST actually means. I’m trying to give you the idea. This post is also addressed to you who think to know what REST means, when in reality you have no clue, just yet. Yes i have met such people in the past – plenty of them. It’s not going into the details of the Richardson Maturity Model, and it’s not gonna make you a REST expert. There are plenty of guides on the web for that: slides, youtube videos, blogposts, books and more. Rather than going into the details, i’m going to link some good resources at the end of this post.

So lets start with

The meaning of REST

Representational State Transfer. This sentence is not only what REST stands for, it is also the tiniest possible description of what REST actually means. Didn’t get it? Read it again: Representational State Transfer. It is not a standard, rather a stlye describing the act of transfering a state of something by its representation.

Lets consider this:
Marcus is a farmer. He has a ranch with 4 pigs, 12 chickens and 3 cows. He is now simulating a REST api while i am the client. If i want to request the current state of his farm using REST i just ask him: “State?”
Marcus answers: “4 pigs, 12 chickens, 3 cows”.
This is the most simple example of Representational State Transfer. Marcus transfered the state of his farm to me using a representation. The representation of the farm is the plain sentence: “4 pigs, 12 chickens, 3 cows”.

So lets get to the next level. How would i tell Marcus to add 2 cows to his farm the REST way?
Maybe tell him: “Marcus, please add 2 cows to your farm”.
Do you think this was REST? Are we transfering state by its representation here? NO! This was calling a remote procedure. The procedure of adding 2 cows to the farm.
Marcus sadly answers: “400, Bad Request. What do you mean?”
So lets try this again. How would we do this the REST way? What was the representation again? It was “4 pigs, 12 chickens, 3 cows”. Ok. so lets try this again transfering the representation…
me: “Marcus, … 4 pigs, 12 chickens,
5 cows … please!”.
Marcus: “Alright !”.
me: “Marcus, … what is your state now?”.
Marcus: “4 pigs, 12 chickens, 5 cows”.
me: “Ahh, great!”
See? It was really not that hard and it was REST.

Why RPC is a pain in the A**

So why would you favor REST over the remote procedure call (=RPC) from a logical perspective? Because it dramatically reduces the complexity of our communication by making the representation our only contract. We do not have to discuss what kinds of procedures we need (Add a cow?, Add an animal of a type? Double the chickens amount? Remove all pigs?). All we have to discuss is the representation, and use this representation to achieve anything we want. Easy, isn’t it? The needless complexity of RPC is not helpful at all. It is rather increasing the risk of misunderstandings, which we don’t want. We don’t want our communication to fail because Marcus and I understood a procedure differently.

But this is just one of many problems RPC is creating. If you want to use RPC you need to design some kind of structure to embed your procedure into. This structure requires a place to store parameters, error codes, return values and so on. I have seen lots of developers and companies who really did this. They designed their own RPC-Structure arising huge problems in the implementation of clients and client-server interaction. Why would you do this? Why would you invent your own RPC-Structure? Do you think this is helpful? What if i wanted to make an application that uses many WebServices of multiple proprietary RPC-Formats? I would have to develop something like this:

If you really need RPC, at least choose a standard like SOAP. Don’t make up your own stuff!

But SOAP is still bad

Still, even the standards of RPC are really painful. Well, i have to admit that with ACID Transactions, and a complete standardized Service Description Language, SOAP is not all that bad under some circumstances. Nevertheless, the overhead SOAP produces is massive and a huge performance killer. HTTP is a lightweight protocol. Its headers include anything you need. The only thing you want to put in the body is a representation – or not even that.

Sessions are Evil

You don’t need sessions! One might say: “But i want to save the customers shopping cart, so i need that session!” – No. Plain Wrong! You can do anything you want without sessions. You could just encapsulate the information of that cart in the URI, or even create another resource for that cart like “/carts/5235″.

Between two requests, you want to be able to turn off the server, uninstall its platform and operating system, dismantle the servers hardware, reassemble the server, reinstall its os, platform and application and restore the backup, without the client even noticing.

Don’t force a client other than a browser (e.g. a smartphone) to store cookies. It is needless complexity and i assure you, it will cause problems. You should even consider to remove statefulness from your webapplication.

Dont reinvent Hypermedia

Since hypermedia is getting quite popular now, i beg you: Don’t invent your own style.
We do already have plenty. There is

And we are slowly getting to this again:

Further Resources

In this post, i have only scratched the surface of the advantages of REST.

Here are some good resources to get you a deeper understanding.


Reference: Why REST is so important from our JCG partner Gregor Riegler at the Be a better Developer blog.
Related Whitepaper:

Functional Programming in Java: Harnessing the Power of Java 8 Lambda Expressions

Get ready to program in a whole new way!

Functional Programming in Java will help you quickly get on top of the new, essential Java 8 language features and the functional style that will change and improve your code. This short, targeted book will help you make the paradigm shift from the old imperative way to a less error-prone, more elegant, and concise coding style that’s also a breeze to parallelize. You’ll explore the syntax and semantics of lambda expressions, method and constructor references, and functional interfaces. You’ll design and write applications better using the new standards in Java 8 and the JDK.

Get it Now!  

12 Responses to "Why REST is so important"

  1. David says:

    I lockstep agree your post. Just one question. What do you really mean with “Don’t force a client other than a browser to save a state”?

    • Gregor says:

      i mean, dont force a client like a smartphone to remember a state. you could do this by using cookies. for example if you open a session on the server it will convey a “SET COOKIE” command to the client. Then the client will have to remember the cookie for all the upcoming requests. This becomes problematic if the authentication is stored in the session. As soon as the session runs out, the Client is not logged in any more, and would have to login again. This is a creepy scenario, because how would you handle it? Login again in the background using the same credentials? What if they changed? Jump to the login screen? What if there is a seperate widget sitting on the home screen in another thread. It gets even more complicated. So what i really ment is don’t let the Client deal with such state.

      Thanks for the Question i’ll make this more clear.

  2. Andre CS says:

    Is it “Representational” instead of “Representional”?

  3. Insurg says:

    Joey: “State?”
    Marcus: “4 pigs, 12 chickens, 3 cows”

    Chandler: “State?”
    Marcus: “4 pigs, 12 chickens, 3 cows”

    Chandler: “Marcus, … 4 pigs, 12 chickens, 5 cows … please!”.
    Marcus: “Alright !”.

    Joey: “Marcus, … 6 pigs, 12 chickens, 3 cows … please!”.
    Marcus: “Alright !”.

    Chandler: “Marcus, … what is your state now?”.
    Marcus: “6 pigs, 12 chickens, 3 cows”.

      • Insurg says:

        Joey: “State?”
        Marcus: “4 pigs, 12 chickens, 3 cows”

        Chandler: “State?”
        Marcus: “4 pigs, 12 chickens, 3 cows”

        Chandler: “Marcus, … 4 pigs, 12 chickens, 5 cows … please!”.
        Marcus: “Alright !”.

        Joey: “Marcus, … 6 pigs, 12 chickens, 3 cows … please!”.
        Marcus: “farm has been modified by Chandler first. Try again please!”.

        Joey: “State?”
        Marcus: “4 pigs, 12 chickens, 5 cows”

        Joey: “Marcus, … 6 pigs, 12 chickens, 5 cows … please!”.
        Marcus: “The farm has been modified by Ross first. Try again please!”.

        Joey: “State?”
        Marcus: “4 pigs, 13 chickens, 5 cows”

        Joey: “Marcus, … 6 pigs, 13 chickens, 5 cows … please!”.
        Marcus: “The farm has been modified by Monica first. Try again please!”.

        • Gregor says:

          Hm, do you think thats better?

          Joey: “Can i update State?”
          Marcus: “No, its currently locked by Ross”
          1 minute later …
          Joey: “Can i update State?”
          Marcus: “No, its currently locked by Monica”

          I dont think so. what if a client forgets to release his lock. This is a scary scenario. The application would have to deal with it.

          • Insurg says:

            Joey: “State?”
            Marcus: “4 pigs, 12 chickens, 3 cows”

            Joey: “Marcus, add 2 pigs please!”.
            Chandler: “Marcus, add 2 cows please!”.
            Monica: “Marcus, add 1 chicken please!”.

            Joey: “State?”
            Marcus: “6 pigs, 13 chickens, 5 cows”

          • Gregor says:

            On your example. the different people still have the problem to not know about other concurrent updates. They just add without caring.
            I agree, that there are scenarios where this could be advantageous.

            but to achieve the same goal you could still do:
            Joey: “POST /pigs”
            Joey: “POST /pigs”

            Marcus: “POST /cows”
            Marcus: “POST /cows”

            Monica: “POST /chicken”

  4. Insurg says:

    > Joey: “POST /pigs”
    > Marcus: “POST /cows”
    > Monica: “POST /chicken”

    So, everyone will be allowed to update own resource. Correct?

  5. Ian says:

    Enjoy the post. Put it in the simplest way: tell them what it looks like when done, not how it needs to be done.

Leave a Reply

7 + eight =

Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books