October 23, 2013

API Management – Derecho REST Exporter

Many legacy applications written in the Spring framework are in production use to meet business requirements. There is a pressing need for such applications to make these services available on smartphones and mobile devices. Users are shifting from the desktop or laptop to their small handheld smartphone devices, so everyone is providing mobile apps to meet users’ expectations and augment their services.

There is a considerable effort involved in building the additional API layer on top of existing services; developers either have to write new Spring controllers or have to use JAX-RS to provide REST service. This is a deterrent to rapid prototyping of the smartphone application itself.

Derecho REST Exporter addresses this issue by analyzing existing Spring services and programmatically generating an API with minimal configuration necessary and no code changes to the services themselves. Derecho REST Exporter is a Java library developed by 3Pillar Labs to expose existing Spring services as a HTTP(s) API with JSON transport.

This post takes a developer’s viewpoint in explaining how the Derecho REST exporter can be deployed in existing Spring applications to quickly provide a REST API suitable for use by mobile application developers.

Integration and Configuration

To expose your Spring services through REST using the Derecho REST Exporter API, you will have to do minimal configuration in your xml file. The following steps are required to configure the Derecho library.

Step 1: Make sure all your services have a corresponding service interface
You should have your services already set up as Spring beans. Each service should consist of a service interface and a service implementation. If this is not the case with one or more of your services, you would need to extract an interface from the implementation.

For example, let us assume you have 2 Spring service interfaces  – UserService and ProductService. Each service has a corresponding implementation class: UserServiceImpl and ProductServiceImpl respectively. You would then already have the following configuration for declaring these implementations as Spring beans:

Step 2: Configure RestExporterService for your beans In the simplest case, if your services have no overloaded methods, you need to declare a com.tpg.labs.derecho.restexporter.RestServiceExporter bean for each such service you want to expose. The RestServiceExporter bean requires two properties: 1.       service: Reference to the service implementation 2.       serviceInterface: Fully qualified name of the service interface

Step 3: Map URL pattern for RestServiceExporter
Map a URL pattern to access this REST service.


Accessing the API

The API is accessed according to the following rules:

1. HTTP Method: All API requests need to be POST requests.

2. Request Path: By default the Java method name is exposed as the last token of the URL pattern mapped to the exporter. For example, with a method name of User#list(...), the request URI would be /derecho/users/list.do.

3. Method Parameters: Method parameters are always specified as a JSON array and need to maintain the same order.


Assuming the UserServiceinterface exposes the following methods:

// service interface
public interface UserService {
  long create(User user) throws SampleException;
  User find(long userId) throws SampleException;
  List list();


// User POJO
public class User {
  private long userId;
  private String userName;
  /* getters and setters not shown */


Java Method Request URL Request Body Response
UserService#create (User) /derecho/users/create.do [{“userName”:”john.denver”}] 1234567890
UserService#find (long) /derecho/users/find.do [1234567890] {“userId”:1234567890,”userName”:”john.denver”}
UserService#list() /derecho/users/list.do (empty) [{“userId”:1234567890,”userName”:”john.denver”}, {“userId”:1023546798,”userName”:”tom.clancey”}]

Other Features

REST exporter has some additional features too as given below:

  1. Custome URL mapping: It has feature to expose service method with a different name instead of given method name.
  2. Handle Overloaded methods: If your service has more than one method with the same name, it can also be handled with this API and expose these methods with the desired custom URL mapping.