Writing REST Services in Java: Part 2 User sign up and Login

Previous Post : Part One: Introduction   Next Post : Part Three: Email Verification
Get the Code: https://github.com/iainporter/rest-java

In this post I will walk through the sign up and login services to demonstrate a vertical slice through the application. I will briefly discuss email verification and Social signup but won't delve into that until the next post. Session handling is also deferred until a later post.

User Sign up

To create a User we need to persist some basic information. At a bare minimum we need an email address and a password. Optionally we would like to capture perhaps a first and last name. 

Once a user has signed up we need them to verify their email address. This is important foremost so that we can uniquely identify the user and provide the ability for them to safely reset their password, as well as other security features that depend on a valid email address being provided.

Most services will follow a similar development pattern to this one which is:

1. Define the domain model

2. Write the Repository interface to persist and retrieve the domain objects

3. Write a Service class to map the API object to the entity and CRUD logic to integrate with the Repository, as well as any other services in support of the particular API.

4. Define the API 

5. Write the Resource Controller

The unit tests will test each layer of the application and the Integration Tests will test the full end to end calls through the application.

The User Domain Object

Entities are defined in the com.porterhead.rest.model package. Hibernate annotations are used to manage the joins and Spring Data to manage some of the basic functions common to all entities. All entities have an additional identifier which is a UUID. Some people have a preference to just use a sequential Long to identify an entity. In this application the primary keys are Longs but UUIDs are used in the API calls to persist and retrieve entities.

It comes down to whether you want your urls to look like this:

/user/1

or like this:

/user/38e1e415-acd2-42bb-8a3f-594f13e0d4ea

All entities that we wish to persist are annotated with:

@Entity
@Table(name="table name")

The class is added to the list of known entities in src/main/resources/META-INF/persistence.xml

The beans responsible for persistence are defined in src/main/resources/META-INF/spring/data-context.xml. There are bean profiles for dev, local, staging and production.

The User Repository

The repository tier uses Spring Data which is an excellent framework that takes care of most of the boilerplate headaches with CRUD functionality. The UserRepository class extends the JPARepository interface and has a few custom finder methods defined.

The User Service

The UserService interface defines a method for creating a new User:

public AuthenticatedUserToken createUser(CreateUserRequest request, Role role);

All entities remain within the boundary of the service layer and API objects pass between the Controllers and the services. This allows us to tightly define the contract between clients and the API. All request and responses are defined in the API package. It also prevents potential transaction and hibernate issues by accessing entity objects outside of a transaction. We can also pass API objects to multiple services without worrying about whether that service knows how to persist a particular entity.

It is worth stepping through the implementation of createUser as it will highlight several key features of how service methods are composed.

The method:

    @Transactional
    public AuthenticatedUserToken createUser(CreateUserRequest request, Role role) {
        validate(request);
        User searchedForUser = userRepository.findByEmailAddress(request.getUser().getEmailAddress());
        if (searchedForUser != null) {
            throw new DuplicateUserException();
        }

        User newUser = createNewUser(request, role);
        AuthenticatedUserToken token = new AuthenticatedUserToken(newUser.getUuid().toString(), createAuthorizationToken(newUser).getToken());
        userRepository.save(newUser);
        return token;
    }

First the API request is validated and if it fails an exception is thrown. This is a common pattern in service methods; to fail fast on an error. All Exceptions extend BaseWebApplicationException which defines an error payload for the response and an appropriate Http status code. In this particular case it will be a 400 error and in the case just below a 409 will be returned for the DuplicateUserException.

If no duplicate is found the a User entity is mapped from the request object and persisted.
Note that the password is saved as a one-way hash salted with the UUID of the User.

Finally an AuthenticatedUserToken object is mapped from the created entity and returned from the method.

See com.incept5.rest.service.UserServiceTest for the full suite of tests to run against this service.

The User Resource Controller

Resource classes are responsible for marshalling and unmarshalling client requests and responses and coordinating calls to services. Resource classes do not access entities but instead use objects in the com.incept5.rest.api package to communicate with services.

There are some JAX-RS annotations to map urls to the correct resource:

@Path("/user")
@Component
@Produces({MediaType.APPLICATION_JSON})
@Consumes({MediaType.APPLICATION_JSON})

The method for sign up is:

    @PermitAll
    @POST
    public Response signupUser(CreateUserRequest request) {
        AuthenticatedUserToken token = userService.createUser(request, Role.authenticated);
        verificationTokenService.sendEmailRegistrationToken(token.getUserId());
        URI location = uriInfo.getAbsolutePathBuilder().path(token.getUserId()).build();
        return Response.created(location).entity(token).build();
    }

We specify that it is a POST and the @PermitAll means that the method is not access controlled. In a later post I will walk through customising a sign up for different types of users (customer, merchant, etc). The general sign up just assigns an authenticated role to a new user.

The logic flow is:

1. Call the User Service to handle the create request. If it is successful an API object will be returned with details of the new User.
2. Call the Email Verification Service to send a welcome email along with an embedded link to verify the email address. The details of this will be discussed in the next post. Note that this an asynchronous call and will return as soon as the Verification Service puts the request onto its queue.
3. A location uri for the new resource is created. This takes the form of user/<uuid>. We will see this in the next section when the API is tested with a curl request.
4. The response is gathered and returned. The Http response will be created (201) and the body will contain an AuthenticatedUserToken. Again I will go into more detail about that later.

Testing the API for User sign up

There are in-memory unit tests in the com.porterhead.rest.resource package for testing the Resource classes  but the surest way to test it is by running the code in a servlet container and firing real requests at it.

The integration tests are in the src/test/groovy directory. The tests are written in groovy and executed using the groovy rest client. UserIntegrationTest has tests for both failure and success scenarios.

Testing the API with curl

To test with curl we need to start up the war in a servlet container. The default profile in gradle.properties is dev but if we wanted to test against a real database and a real mail sender we could change that to local or staging and configure the necessary beans. I will discuss how to do that later.

Execute the following command:

gradle tomcatRun

Once the war has finished loading we can execute the following curl request:

curl -v -H "Content-Type: application/json" -X POST -d '{"user":{"firstName":"Foo","lastName":"Bar","emailAddress":"<your email address here>"}, "password":"password"}' http://localhost:8080/java-rest/user

You should see a response like this:

< HTTP/1.1 201 Created
< Server: Apache-Coyote/1.1
< Location: http://localhost:8080/java-rest/user/ff7ffcf0-cfe0-4c1e-9971-3b934612b154
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Sat, 12 Jan 2013 09:43:13 GMT
<  * Connection #0 to host localhost left intact
{"userId":"ff7ffcf0-cfe0-4c1e-9971-3b934612b154","token":"5d1cf32e-e468-4a2c-92b6-9b0c377145f9"}

I'll discuss how to use the response in the next post.

Now that we know sign up works we can test out login.

Try the following curl statement:

curl -v -H "Content-Type: application/json" -X POST -d '{"username":"<your email address here>","password":"password"}' http://localhost:8080/java-rest/user/login

The response:

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Location: http://localhost:8080/java-rest/user/7ef646ba-5e03-4d59-90a9-822daecf3428
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Sat, 12 Jan 2013 09:52:21 GMT
<
* Connection #0 to host localhost left intact
{"userId":"7ef646ba-5e03-4d59-90a9-822daecf3428","token":"164797a0-623f-427d-a469-b348e7e2bc59"}

That covers user sign up and login. In the next post I will discuss the email verification process.