Wednesday, June 11, 2014

Open source RESTful server application (Dropwizard - Google Guice - JPA Hibernate)

Around one year ago I decided to use the Java framework Dropwizard for our server application. Since then I read a lot, I learned a lot and I implemented many things.

As the recently published new Dropwizard version required some re engineering of our application, I used the opportunity to start all over again from the beginning to strengthen my knowledge about the whole implementation. I want to permanently understand every single detail of it, that's the only way I can extend and document it in a meaningful way. It should also help other people to get involved in the development!

In order to be able to provide my technical progress to the outside world in a useful way, I created a complete new ToDo application which is generic, thus stripped of the whole Oregami context. You know the drill with those to-do's: an incomplete thing with a list of features (name, description, state, ...) that still need doing.

Today the generic application contains the following stuff:
  • RESTful app based on Dropwizard version 0.7.0
  • Dependency Injection with Google Guice
  • Hibernate / JPA 2.1 as persistence framework
  • HSQLDB as (in memory) database
  • "Transaction-per-HTTP-request" with Guice PersistentFilter
  • Support for cross-origin resource sharing
  • JPA entities with UUIDs as key
  • a pattern for accessing and manipulating entities with HTTP REST calls
    (Resource => Service => DAO => entity)
  • a pattern for ServiceResult objects which contain ServiceErrorMessages (which can later be bound to the corresponding web form fields in the client)
  • continuous JUnit tests to assure correct functionality
In the near future the following aspects should be added:
  • authentification
  • Hypermedia with HATEOAS
  • more complex entities (1-to-n-relations)
The complete source code is available for everybody at Github as dropwizard-guice-jpa-seed.

Disclaimer: Of course you might find out that something can be done in a better way. In this case don't hesitate and help me to improve the code! Use the usual pull request mechanism at Github to do so. The same applies for extensions of the functionality!

Notes for developers:

Start the application with the class "ToDoApplication" with the parameters "server todo.yml".

List all tasks with:
GET => http://localhost:8080/task


Add a new task with:
POST => http://localhost:8080/task

Header:
Content-Type:application/json
JSON-Body e.g. :
{"name" : "task 1", "description" : "This is a description"}


Modify a task:
PUT => http://localhost:8080/task/[id]
Header:
Content-Type:application/json
Accept:application/json

JSON-Body e.g.:
{
    "id": "402880944687600101468760d9ea0000",
    "version": "0",
    "name": "task 1 with new name",
    "description": "This is an updated description",
    "finished": "false"
}


Important hint:
I recommend you use the great chrome extension Postman to make such HTTP calls!