Introduction

REST-based APIs are becoming more and more popular around the web and the number of services based on REST are constantly increasing. Apache Wicket is well-known for its capability of transparently handling the state of web applications on server side, but it can be easily adopted to create RESTful services as well.

With the last release of WicketStuff project (version 6.10.0) we can find the Wicket REST annotations module that allows us to develop REST applications/APIs in much the same way as we do it with Spring MVC or with the standard JAX-RS.

In this article, we will explore the basic features and the artifacts offered by the Wicket REST annotations module to implement the REST architecture with Apache Wicket.

The REST Annotations module in short

The central element of the module is the abstract class  AbstractRestResource that is a generic class to implement a Wicket resource that handles the request and the response using a particular data format (like XML, JSON, etc...). As JSON is de-facto standard format for REST API, the project comes also with a ready-to-use resource called GsonRestResource that works with the JSON format.

The example sub-module contains resource PersonsRestResource which subclasses GsonRestResource and implements a simple REST service to handle instances of the following bean:

package org.wicketstuff.rest.domain;

public class PersonPojo {
  private String name;
  private String email;
  private String password;

  public PersonPojo(String name, String email, String password) {
    this.name = name;
    this.email = email;
    this.password = password;
  }
}

To indicate which methods must be invoked to serve REST requests, we must use annotation  MethodMapping . Its basic usage is quite simple and intuitive, as we can see in the code of PersonsRestResource:

public class PersonsRestResource extends GsonRestResource {
  private final List<PersonPojo> persons = new ArrayList<PersonPojo>();

  @MethodMapping("/persons")
  public List<PersonPojo> getAllPersons() {
    return persons;
  }

  @MethodMapping(value = "/persons/{personIndex}", httpMethod = HttpMethod.DELETE)
  public void deletePerson(int personIndex) {
    persons.remove(personIndex);
  }

  @MethodMapping(value = "/persons", httpMethod = HttpMethod.POST)
  public PersonPojo createPerson(@RequestBody PersonPojo personPojo) {
    persons.add(personPojo);
    return personPojo;
  }
}

The two required attributes for MethodMapping are the subpath to use to mount the method and the HTTP method to map to. The final path for the mapped method will be the path the resource is mounted at plus the value expressed in MethodMapping. This value can contain path variables that can be used as parameters for mapped methods (like personIndex in the code above).

To promote the principle of convention over configuration, we don't need to use any annotation to map method parameters to path parameters if they are declared in the same order (but we can always decide to do this manually, as we will see shortly).

If a mapped method returns a value, this latter will be serialized to JSON and written to the response. The code above shows also how to do the inverse procedure (i.e. reading an object serialized as JSON from request body) with annotation RequestBody (method createPerson).

To convert strings to Java type, AbstractRestResource uses the standard Wicket mechanism based on the application converter locator:

//return the converter for type clazz
IConverter converter = Application.get().getConverterLocator().getConverter(clazz);
//convert string to object
return converter.convertToObject(value, Session.get().getLocale());

This is all we have to know to start using REST with Wicket. The Wicket REST annotations module offers more advanced features such as regular expression for path parameters and integration with Wicket role based authorizations.

To learn more about these advanced features you can go to the project page  where you will find an exhaustive documentation about this new module.