What is spring-data-rest?
spring-data-rest, a recent addition to the spring-data project, is a framework that helps you expose your entities directly as RESTful webservice endpoints. Unlike rails, grails or roo it does not generate any code achieving this goal. spring data-rest supports JPA, MongoDB, JSR-303 validation, HAL and many more. It is really innovative and lets you setup your RESTful webservice within minutes. In this example i'll give you a short overview of what spring-data-rest is capable of.
Initial ConfigurationI'm gonna use the new Servlet 3 Java Web Configuration instead of an ancient web.xml. Nothing really special here.
WebAppInitializer.java on github
I am initializing hibernate as my database abstraction layer in the AppConfiguration class. I'm using an embedded database (hsql), since i want to keep this showcase simple stupid. Still, nothing special here.
AppConfiguration.java on github
Now to the application servlet configuration: WebConfiguration
WebConfiguration.java on github
Oh, well thats a bit short isnt it? Not a single line of code required for a complete setup. This is a really nice application of the convention over configuration paradigm. We can now start creating spring-data-jpa repositories and they will be exposed as RESTful resources automatically. And we can still add custom configuration to the WebConfiguration class later if needed.
The Initialization was really short and easy. We didn't have to code anything special. The only thing we did was setting up a database connection and hibernate, which is obviously inevitable. Now, that we have setup our "REST Servlet" and persistence, lets move on to the application itself, starting with the model.
The ModelI'll keep it really simple creating only two related entities.
Author.java on github
To finally make the entities persistent and exposed as a RESTful webservice, we need spring-data repositories. A repository is basically a DAO. It offers CRUD functionality for our entities. spring-data takes away most of your programming effort creating such repositories. We just have to define an empty interface, spring-data does everything else out of the box. Still, it is easily customizable thanks to its design by convention over configuration!
The Actual Repositories
BookRepository.java on github
AuthorRepository.java on github
Again, there is nearly no code needed. Even the @RestResource annotation could be left out. But if i did, the path and rel would be named after the entity, which i dont want. A REST resource that contains multiple children should be named plural though.
Accessing The ResultOur RESTful webservice is now ready for deployment. Once run, it lists all available resources on the root, so you can navigate from there.
Fine! Now lets create an author and a book.
201 Created Location: http://localhost:8080/authors/1PUT http://localhost:8080/books/0132350882
201 CreatedNoticed how i used PUT to create the book? This is because its id is the actual isbn. I have to tell the server which isbn to use since he cant guess it. I used POST for the author as his id is just an incremental number that is generated automatically. Also, i used a link to connect both, the book (/books/0132350882) and the author (/authors/1). This is basically what hypermedia is all about: Links are used for navigation and relations between entities.
Now, lets see if the book was created accordingly.
Here is an Integration Test, following these steps automatically. It is also available in the example on github.
BookApiIT.java on github
ConclusionWe have created a complete RESTful webservice without much coding effort. We just defined our entities and database connection. spring-data-rest stated that everything else is just boilerplate, and i agree.
To consume the webservices manually, consider the rest-shell. It is a command-shell making the navigation in your webservice as easy and fun as it could be. Here is a screenshot:
The complete example is available on my github