Why REST is so important

This post is dedicated to REST, an architectural style of shaping webservices and one of 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 style 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 Representional 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:

image #1

Ugh...
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 in 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

Since i wrote solely about sessions and why they are bad in another post, i removed this paragraph. Please continue reading here: Sessions. A Pitfall

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

• Hypermedia by the Atom Link specification like in spring-hateoas and spring-data-rest.
• JSON-HAL
• JSON-LD
• ...

And we are slowly getting to the situation in image #1 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.

• Fowlers Article on the Richardson Maturity Model
• A great slide on Hypermedia
• A talk by David Zuelke on RESTful Webservices
• Intro to REST (short video of GoogleDevelopers)
• A talk of Lez Hazlewood (Stormpath)
• A Cookbook for RESTful WebServices
• Great German Book about REST

Spring MVC - @RequestBody and @ResponseBody demystified

In this post i want to dig into spring mvc a little, revealing what happens behind the scenes when a request is converted to your parameter object and vice versa. Before we start, i want to explain the purpose of these annotations.

What are @RequestBody and @ResponseBody for?

They are annotations of the spring mvc framework and can be used in a controller to implement smart object serialization and deserialization. They help you avoid boilerplate code by extracting the logic of messageconversion and making it an aspect. Other than that they help you support multiple formats for a single REST resource without duplication of code. If you annotate a method with @ResponseBody, spring will try to convert its return value and write it to the http response automatically. If you annotate a methods parameter with @RequestBody, spring will try to convert the content of the incoming request body to your parameter object on the fly.

Here is an example

@Controller
@RequestMapping(value = "/bookcase")
public class BookCaseController {

    private BookCase bookCase;

    @RequestMapping(method = RequestMethod.GET)
    @ResponseBody
    public BookCase getBookCase() {
        return this.bookCase;
    }

    @RequestMapping(method = RequestMethod.PUT)
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void setBookCase(@RequestBody BookCase bookCase) {
        this.bookCase = bookCase;
    }

}

So what is Spring doing behind the scenes when we are using those Annotations?

Depending on your configuration, spring has a list of HttpMessageConverters registered in the background. A HttpMessageConverters responsibility is to convert the request body to a specific class and back to the response body again, depending on a predefined mime type. Every time an issued request is hitting a @RequestBody or @ResponseBody annotation spring loops through all registered HttpMessageConverters seeking for the first that fits the given mime type and class and then uses it for the actual conversion.

How can i add a custom HttpMessageConverter?

By adding @EnableWebMvc respectively <mvc:annotation-driven />, spring registers a bunch of predefined messageconverters for JSON/XML and so on. You can add a custom converter like the following

@Configuration
@EnableWebMvc
@ComponentScan
public class WebConfiguration extends WebMvcConfigurerAdapter {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> httpMessageConverters) {
        httpMessageConverters.add(new BookCaseMessageConverter(new MediaType("text", "csv")));
    }
}

In this example i've written a converter that handles the conversion of a BookCase, which is basically a List of Books. The converter is able to convert csv content to a BookCase and vice versa. I used opencsv to parse the text.

Here is the model

public class Book {

    private String isbn;

    private String title;

    public Book(String isbn, String title) {
        this.isbn = isbn;
        this.title = title;
    }

    // ...
}

public class BookCase extends ArrayList<Book> {

    public BookCase() {
    }

    public BookCase(Collection<? extends Book> c) {
        super(c);
    }
}

and the actual converter

public class BookCaseMessageConverter extends AbstractHttpMessageConverter<BookCase> {

    public BookCaseMessageConverter() {
    }

    public BookCaseMessageConverter(MediaType supportedMediaType) {
        super(supportedMediaType);
    }

    public BookCaseMessageConverter(MediaType... supportedMediaTypes) {
        super(supportedMediaTypes);
    }

    @Override
    protected boolean supports(Class<?> clazz) {
        return BookCase.class.equals(clazz);
    }

    @Override
    protected BookCase readInternal(Class<? extends BookCase> clazz, HttpInputMessage httpInputMessage) throws IOException, HttpMessageNotReadableException {
        CSVReader reader = new CSVReader(new InputStreamReader(httpInputMessage.getBody()));
        List<String[]> rows = reader.readAll();
        BookCase bookCase = new BookCase();
        for (String[] row : rows) {
            bookCase.add(new Book(row[0], row[1]));
        }
        return bookCase;
    }

    @Override
    protected void writeInternal(BookCase books, HttpOutputMessage httpOutputMessage) throws IOException, HttpMessageNotWritableException {
        CSVWriter writer = new CSVWriter(new OutputStreamWriter(httpOutputMessage.getBody()));
        for (Book book : books) {
            writer.writeNext(new String[]{book.getIsbn(), book.getTitle()});
        }
        writer.close();
    }
}

The Result 

We can now issue text/csv requests to our Resource along with application/json and xml which are basically supported out of the box.

1.)

PUT /bookcase
Content-Type: text/csv
"123","Spring in Action"
"456","Clean Code"

Response
204 No Content

2.)

GET /bookcase
Accept: text/csv

Response
200 OK
"123","Spring in Action"
"456","Clean Code"

Thanks to the design of spring mvc, which is following the single responsibility principle, our controller stays thin. We don't have to add a single line if we want to support new media types.

The complete example is available on my github

Modern Web Development

In the last few years web technology has lived through rapid growth and heavy change. We went from frames to table layouts, to column layouts, to responsive layouts. From html4 to xhtml & flash to html5. From heavy server to rich client. From rpc to soap to rest. From sql to nosql and big data. From MVC to MVP and so on. In the following post i want to describe what has become state-of-the-art from my perspective.

A Backend is a REST api 

Every backend should be seen as a REST api and every controller as another resource. You want to analyze your problem domain, find your resources and design proper paths for them. They become the M in your MVC Architecture. Developing a webapplication first, and adding an extra REST api later on has to be considered an antipattern. If you do make a REST api, you want to consequently use it yourself, making your frontend its first consumer. This procedure allows you to smoothly add different kinds of clients later on, such as a mobile app or even a desktop application. It's also the foundation to integrate your applications features into other applications.

Separate your Frontend

The days when you made up a form using jsp with a jstl form validation are fading. You don't want to mix client with server technology anymore. The V and C of MVC has shifted over to the client and your backend just represents the Model. You want your frontend to be completely separated using client technology only (html/css/js) and consuming your REST api. GUI logic, building and aligning proper html elements can be achieved within javascript. The most appropriate content-type for information exchange between the backend and frontend would be json or even xml.

Rich Client & Hail JavaScript

The MVC pattern is nowadays implemented on the client side using javascript and it's fellow frameworks. There is no full-blown complete javascript framework that can achieve everything out of the box, but there are tons of smaller libs solving atomic tasks. This should not be considered bad or overwhelming, but advantageous. It causes a great variety of tools that focus on solving single problems outright. Backbone is a popular mvc framework built upon underscore, a js library delivering great utility with remarkable functional programming features. A template engine like mustache or handlebars could be added and requirejs would manage the dependencies within your modules. Of course, a dom manipulator like jquery cannot be left out. The trend is leading towards SPA's (Single Page Applications) with heavy AJAJ/AJAX, routing through html #anchors representing bookmarkable view-states.

Implement a Buildprocess for your Frontend

As Browsers are continously increasing javascript performance and adding more and more support for html5, frontends have become complex and sophisticated. You now want to add a build process for your frontend, compiling all your js and css files. You want to deliver only a single minified js file to the browser. Other than that we don't break the DRY principle writing styles anymore. We use dynamic stylesheet languages like less to make our styles smarter and cleaner and compile them to css in our build process. Node and rhino are possible engine candidates to build your frontend. While node is much faster, it requires an easy installation on the build server. Rhino runs in a jvm, thus not requiring an installation. You can add it to your project as a maven dependency.

Mobile Web & Responsive Design

Mobile devices are becoming more powerful in terms of hardware whilst html5 support is also rapidly increasing on mobile browsers. Html5 could potentially make native mobile applications obsolete one day. Localstorage, SQL, Geolocation, Multimedia, Camera Access, Web Sockets, Graphics, Touch Events, WebGL, Filesystem Access, Notifications and many more are all features to be completely available to mobile html5 webapplications one day, hopefully working on all devices. So far, we have been developing multiple applications for android/ios/windows mobile and so on, being an economic nightmare.
Mobile clients have gained a substantial amount in web consumership, and cannot be ignored anymore. Therefor you want to make your GUI reponsive, beeing able to scale down to smaller display-resolutions. Wise companies have even started designing userinterfaces for the smallest resolution before even thinking of a desktop resolution. This makes scaling more easy, since the other way round is harder and tends to force painfull workarounds. Bootstrap is one of many libraries that help you make your gui responsive. You can use initializr to get started.

GWT or ZK Framework? Use Neither!

GWT/ZK are trying do deliver a framework that makes it possible to develop modern ajax web applications using Java only. So they are basically building a java wrapper for frontend technology. Other than that, they deliver a huge amount of components. BUT ... i'd like to question their philosophy for many reasons.

• They Both produce quite bad html code making you end in an element and dom-id nightmare that gets hard or even impossible to test, debug and style. Html5 allows to write short, clean and readable code, organized way better. You want to write html yourself.
• Their AJAX calls are not based on the REST api that you need. If you want a REST api, you may have to write that again. RPC is GWT's primary communication-technology and i am really concerned about that. But you can still make a REST api work with GWT if you like to.
• They keep you away from the technology that you are actually producing. Tiny customizations can get hard or even impossible in the end. You are basically giving up control and limiting your possibilities. This might in many cases lead to dead ends, that are based on the framework, not the technology. GWT helps to overcome this problem offering JSNI.
• They are never up to date. While browsers are evolving rapidly, new features have to be implemented in the Java-Wrapper before you can even use them, delaying your up-to-dateness.
• I doubt that wrapping native front-end technology is a good idea, and i don't see a reason for doing it. One pro GWT argument might be: it's generating optimized JS code.

In the end they make it easier to build webapplications for former java.awt/swing developers, who have no to little knowhow on html/css/js.
They defintively have their place right now and aren't a bad choice in some cases.