Restful Web Service Guide

Nowadays more and more projects are developed using the tuple AngularJs in frontend + Java EE (or Spring Framework) in backend. The communication between AngularJs and Java EE is done by using Restful Web Services. 

In my company this tuple is implemented in every project and we are several teams working on different projects. So it seems clear that it would have sense that all Restful Web Services should be done in similar way. For this reason we (the architecture team) decided to create a Restful Web Service guide where all teams could base their API design. In this document we mention basic concepts of Rest, but also how to internationalize a Rest API, Pagination, Security with Json Web Tokens or Http Error codes.

This guide has been released under CC license and is published in github. You can watch it without any problem, send a PR with any improvement or open an issue to discuss anything.

It is located at http://scytl.github.io/restguide/.

We keep learning,
Alex.

It might seem crazy what I'm about to say, Sunshine she's here, you can take away, I’m a hot air balloon, I could go to space ,With the air, like I don't care baby by the way (Happy - Pharrell Williams)

Music: https://www.youtube.com/watch?v=y6Sxv-sUYtM

RESTful Java Patterns and Best Practices Book Review

Past week I have been reading the book RESTful Java Patterns and Best Practices written by Bhakti Mehta. It is a good introduction book of RESTful patterns which compares how common REST API problems like pagination or internationalization are solved by companies like GitHub, Facebook or Twitter. Also there is one introductory chapter to HATEOAS.

The book is well-written and faces clearly each problem and how can be solved. Also compares how the same problem has been implemented by different companies, comparing their approaches and what are the advantages and disadvantages of each one.

Maybe as something to be improved for my taste is the examples. In my opinion (maybe because of my expectations), the code examples are simple, which on one side is good because they are easy to follow but on the other side you will need to search on internet to find more complex examples on how to implement what is described in the book. Of course this will depend on your knowledge of REST and JAX-RS.

Overall a good book to read, easy understanding and a good starting point for RESTful patterns.

Testing client side of RESTful services

People tell me A and B, They tell me how I have to see, Things that I have seen already clear, So they push me then from side to side (I Want Out - Helloween)

Develop an application that uses RESTful web API may imply developing server and client side. Writing integration tests for server side can be as easy as using Arquillian to start up server and REST-assured to test that the services works as expected. The problem is how to test the client side. In this post we are going to see how to test the client side apart from using mocks.

As a brief description, to test client part, what we need is a local server which can return recorded JSON responses. The rest-client-driver is a library which simulates a RESTful service. You can set expectations on the HTTP requests you want to receive during a test. So it is exactly what we need for our java client side. Note that this project is really helpful to write tests when we are developing RESTful web clients for connecting to services developed by third parties like Flickr Rest API, Jira Rest API, Github ...

First thing to do is adding rest-client-driver dependency:

Next step we are going to create a very simple Jersey application which simply invokes a get method to required URI.

And now we want to test that invokeGetMethod really gets the required resource. Let's suppose that this method in production code will be responsible of getting all issues name from a project registered on github.

Now we can start to write the test:

• We use ClientDriverRule  @Rule annotation to add the client-driver to a test.
• And then using methods provided by RestClientDriver class, expectations are recorded.
• See how we are setting the base URL using driver.getBaseUrl()

With rest-client-driver we can also record http status response using giveEmptyResponse method:

And obviously we can record a put action:

Note that in this example, we are setting that our request should contain given message body to response a 204 status code.

This is a very simple example, but keep in mind that also works with libraries like gson or jackson. Also rest-driver project comes with a module that can be used to assert server responses (like REST-assured project) but this topic will be addressed into another post.

I wish you have found this post useful.

We keep learning,

Alex.

Source Code

Music: http://www.youtube.com/watch?v=FjV8SHjHvHk

Sábado na balada, A galera começou a dançar, E passou a menina mais linda, Tomei coragem e comecei a falar (Ai se eu te pego - Michel Teló)

Backbone is a Javascript library that provides a clean way to:

• define models in Javascript.
• deal with Collections using a rich API.
• define Views with declarative event handling and template support.
• interface to Rest architectures.

In current post I am going to use the Rest WebApp of my old post, where I only explained the server side to show you how to implement client side using Backbone.

So the first thing to do is create a web structure into IDE, for this example I will reuse same project of RestServer post.

Then download backbone.js and its dependencies and copy to webapp/resources/js directory:

• json2
• jquery 1.5
• underscore 1.2.3
• backbone 0.5.3

Open servlet-context.xml and add root and  js folder as static resource.

Then go to webapp/resources and create index.html.

Add all Javascript libraries into page, but most important, add them in the same order as appears here, if not, some Javascript failures would appear in your browser and the application will not work.

Note that some content is created directly using HTML tags rather than using Backbone views. Normally page layout, headers, footers ... are treated as static content and they are directly written into page.

Let's start modeling our data, in this case a character with its attributes (id, name, url, isHuman...).

Models in Backbone has a particularity that make them useful, they are an implementation of Active Record pattern, so when you are creating a model you will have CRUD operations against a Rest-WebService. So for example when you call save method of your model, Backbone converts that model to JSON and sends the result to server as HTTP POST (if model has no id), or HTTP PUT (update). Other available operations are fetch (load) and destroy (delete).

See how in this case we have created a Character model setting urlRoot property. This property is used to build endpoint to ResetServer.  As long as the endpoint returns JSON for a single character, properties will be merged into model.

And the same applies to Collections. When you call fetch method of characters var, all characters returned by calling GET .../characters will be stored into.

See how easy is implementing a Rest Client using Backbone. And I suppose you are wondering where are attributes' definition? Don't worry, with Backbone is not necessary to explicitly define at definition time.

Now it is time for Views. As I cited at the begin of post, Backbone has template support. For this example two templates are going to be used, one for filling a new character and another for showing character information.

To define a template you must use <script> tag with text/template type instead of text/javascript and an id. The structure is similar to JSP (embedded HTML code, <%= %> for printing variables and <% %> for logical structures).


Next step is creating Views. 

For this example we are going to create three views, one for each template, and one that will be a composition of both.

Let's start with View responsible of showing information of one character.

At line 3 we are loading template content defined previously with id show-characters, into showCharactersTemplate object.

Next important line is number 6. There we are defining a function that will be invoked each time we want to render a view (one time per character). See how we are passing a model object (trust me it is not defined yet, but will be there), to template. To fill template variables, template engine requires data in JSON format, and Backbone model has a toJSON method.  And finally generated html code is saved into el attribute.

Next View is responsible of showing character form, and deal with submit action.

This View shows events handling in Backbone. See line 9. We are defining that when user clicks on tag element "a" with class submit, element defined in new-character template, createOnEnter function is executed.

createOnEnter method does three things:

• gets values from template form.
• instantiates CharacterModel class. See that this is the place where model attributes are defined.
• calls save method. This method sends object data to defined endpoint at server side. Because this operation is asynchronous, a callback is registered, so when a success is received, character is added into characters list.

And last View is a composite view of two previous views, acts as a controller between adding a new character and showing all inserted characters:

Initialize function does all required initializations so UI could be refreshed asynchronously. In first two lines we are binding add and reset functions of characters collection to a method. For example each time add function is called, addCharacter is invoked.

Next line is used to populate data to Collection. When fetch is called an HTTP GET to defined endpoint is sent, data is retrieved and Collection's add method is called for each result.

addCharacter function is responsible of creating one View for each character. There is not much secret, we are creating a CharacterView, and appending the result of calling its render method to html element with character-list id.

And finally render function that is responsible of rendering CharacterFormView.

See that page is only loaded first time we access it, subsequent updates are done by DOM manipulations.

To finish I embedded all html file explained here so you can see a global overview of all pieces used. Also feel free to download all Eclipse project. I wish you find this post useful.


Download Code

Music: http://www.youtube.com/watch?v=q1Ebi9cSn48

Can't you see, It all makes perfect sense, Express in dollars and cents, Pounds shillings and pents, Can't you see, It all makes perfect sense (Perfect Sense Part II - Roger Waters)

REST INTRODUCTION

From Wikipedia: REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed.

As you have read the most important thing in Rest architecture is the existance of a resource. This resource  can be anything (typically required information requested by client) that can be identified with a global identifier (URI in case of HTTP). In order to manipulate these resources, client communicates using standard interfaces (like HTTP) and exchange representations of these resources (using HTML, XML, ...).

Note that Rest does not force you to use any specific network protocol nor how resources are identified.

For those who have never read about Rest this description of Rest architecture could seem something strange and bit complicated. 

A RESTful web service is a simple web service implemented using HTTP and the principles of REST. URI is defined as global identified, communication interface is HTTP and resource representation can be any valid Internet media type like JSON, XML or YAML. The set of operations that can be executed to resources depend on HTTP Methods and are (GET - retrieving/listing, PUT - replacing/updating, POST - creating and DELETE - deleting).

HANDS ON WORK

Let's create our first Rest application with help of Spring MVC. Imagine an application that has a database of manga characters, and you want to provide a Rest interface so clients can retrieve characters following a RESTful strategy.

First thing to do is identify the resource. In this case it is easy, "a character". Next step is finding a URI that determines unequivocally a character. Easy too de facto rule can be applied here. This rule suggests that a unique URI can be <host>/<applicationname>/<resourceName>s/<id> in our case to return (GET) character with id 1 the URI would be "http://localhost:8080/RestServer/characters/1". If no identifier is present all characters should be retrieved. If instead of GET, POST is used, a character with id "1" would be inserted. And finally decide which Internet media type is required, in this case doesn't matter because we are implementing both client and server so initially XML will be used.

CODING

Let's start with a simple Spring MVC application created with Spring MVC template. Not much secret here, you will have a servlet-context.xml where component-scan, annotation-driven and InternalResourceViewResolver are registered.

Next step is defining Character class. A simple POJO with four attributes. Class is converted to its XML representation using Jaxb annotation.  Jaxb allows developers to map Java classes to XML representations and viceversa.

And finally the most important class in Spring MVC, "The Controller". Controller will be the responsible of implementing required operations of Character resource. In current case only GET is implemented, the other operations would be similar. Let's see the code:

First part is a map where all characters are stored. I have used this approach to not focus in data access. Then findCharacter method that is called when URI is /characters/{characterId}. This is a URI template and is a URI-like string, containing one or more variable names, which can be accessed using @PathVariable annotation. So when you are accessing to /characters/1 parameter characterId is bound to 1.

Last important part is @ResponseBody annotation. This annotation can be put on a method and indicates that the return type should be written straight to the HTTP response body, and not placed in a Model, or interpreted as a view name as standard behaviour of Spring MVC. So findCharacter method returns a Character object.

And that's all if you execute this code, and for example you enter URI http://localhost:8080/RestServer/characters/1 the output (using RestClient UI) will be:

And now is when you are wondering, ¿If I am returning a Character object and output is a XML, where is conversion between object and XML? So easy, let me introduce a new concept: HttpMessageConverters. HttpMessageConverter is responsible for converting from HTTP request message to an object and converting from an object to HTTP response body. Next HttpMessageConverters are registered by default:

- ByteArrayHttpMessageConverter

- StringHttpMessageConverter

- ResourceHttpMessageConverter

- SourceHttpMessageConverter

- XmlAwareHttpMessageConverter

- Jaxb2RootElementHttpMessageConverter

- MappingJacksonHttpMessageConverter

So now you understand why works perfectly. When you are returning Character instance, Jaxb2RootElementHttpMessageConverter using canWrite method checks if class contains XmlRootElement annotation. If class is annotated, write method is called. In this case Jaxb marshaller is called, and XML is returned. Same from XML to object but using Jaxb unmarshaller class.

So easy, no complicated configurations, no complicated mappings, no unclear code, and you only need to worry about your model objects, not in conversion. But let me introduce one change. Now instead of returning XML we want to return JSON.

Change could not be easier, add Jackson library to pom.xml and change @XmlRootElement to @JsonAutoDetect. And now MappingJacksonHttpMessageConverter will handle this object and will transform Character instance to JSON protocol using Jackson library. Only changing one line of code!!!

And now output will be:

CONCLUSIONS

Of course this is a very simple application with only one operation, but it gives you an idea of how to develop Restful web services using Spring MVC. It is a matter of time of writing all your required operations using same approach that I have used with GET.

Arriving at this point I think that all of us have arrived to same conclusion. Annotations are really really powerful, and Spring MVC fits perfectly for developing RESTful web services.

See you next time.

Music: http://www.youtube.com/watch?v=RiFC8nLfiUw

Download Code.