Writing REST services in Java: Part 1 overview

This is the first in a series of posts walking through setting up a REST application in java. The code accompanying it can be found here https://github.com/iainporter/rest-java

The application contains all the necessary parts to start building new services and deploy them quickly and easily. After checking out the code and making a few configuration changes you can deploy a fully functioning API that includes:

* Signing up a user
* Logging in a user
* Facebook authentication
* Sending email verification
* Verifying email responses
* JSR 303 Validation
* Lost Password
* Role-based authorization
* Request signing
* Session Expiry

I will walk through the various parts in subsequent posts. This will include:

• Part 1: An introduction to writing REST Services in Java
• Part 2: User sign up and login
• Part 3: Email Verification
• Part 4: Facebook Authentication
• Part 5: Lost Password
• Part 6: Security & Authorization
• Part 7: Moving to Production
• Part 8: JSR 303 Validation
• Securing REST APIs with OAuth2

Technologies covered will include:

* Jax-RS (Jersey implementation)
* Spring Data
* Hibernate
* Spring Integration
* Java Mail
* Velocity
* Groovy (for Integration Tests only)
* Deploying to AWS

Building the project 

The project uses gradle to build and deploy. If you don't have gradle installed get it here http://www.gradle.org/

To debug when running in tomcat you can add the following to your bash profile:

export GRADLE_OPTS="-Xmx1024m -XX:MaxPermSize=128M -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8787"

If you have gradle installed then navigate to the root directory and execute

gradle clean build integrationTest

Once it has finished you can inspect the results in build/reports.

Running the Application

From the root directory execute

gradle tomcatRun

When the servlet container has loaded the war run the following curl request:

curl -v -H "Content-Type: text/html" -X GET  http://localhost:8080/java-rest/healthcheck

You should see the following response:

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: text/plain
< Transfer-Encoding: chunked
< Date: Thu, 10 Jan 2013 19:21:02 GMT
< Running version 1.0.0

The application is now successfully running.

The Project Structure

At the root there are two files that control how the project is built:

build.gradle
gradle.properties

Build Tasks

gradle clean - cleans out the build directories
gradle build - compiles the source, runs the unit tests, writes test and coverage reports, builds the WAR file
gradle integrationTest - runs the groovy integration tests and appends to the test report
gradle tomcatRun - starts the tomcat container and loads the WAR file

Spring Profiles

The project makes use of Spring Profiles. When running from gradle commands the active profile is loaded from the gradle.properties file.

There are four profiles:

dev - runs in-memory database, Mock Mail Sender

local - runs against local instance of mySQL DB, Mock Mail Sender
staging - runs against a configured DB instance and configured staging Mail Sender
production - runs against a configured DB instance and configured production Mail Sender

Unit Tests and Code Coverage

Unit tests are in the src/test/java directory and are ran against the DEV profile. 

Integration tests are in the src/test/groovy directory. These tests are ran in a Jetty servlet container against the DEV profile. You can change the profile to local if you want to capture the results in your local DB store. The main principle of the integration tests is that they exercise the API in the guise of a client. This means that all requests and responses are json structures and not built against any server side API components.

Code coverage uses the emma plugin

The Architecture

A typical message flow is:

1. The client makes a RESTful request (either PUT, POST, GET or DELETE) using Json payloads.

2. The servlet filter routes all requests through the Authorization filter.

3. If there is a valid Authorization header the authorization service performs validation and identifies the User making the request

4. Control is passed to the Resource Controller that handles resources of that type. 

5. A Roles-based filter checks the user has access control for that resource request.

6. The Json payload (if present) is marshalled to an API object

7. The Resource Controller communicates with one or more Services by passing back and forth API objects

8. The Service tier is responsible for managing the lifecycle of entities and integration with any external services as well as transformation mappings between entities and API objects

9. The Repository tier manages persistence and retrieval of entities

10. Responses are returned by the Resource Controllers, unmarshalled to Json and returned to the client

In the next post I'll dig into the details of sign up and login.