A Lightweight Alternative to JAX-RS

HTTP-RPC is an open-source framework for simplifying development of REST applications. It allows developers to access REST-based web services using a convenient, RPC-like metaphor while preserving fundamental REST principles such as statelessness and uniform resource access. The project currently includes support for consuming web services in Objective-C/Swift and Java (including Android), making it easy to interact with services regardless of the target device or operating system.

HTTP-RPC also includes optional support for implementing REST services in Java, providing a lightweight alternative to larger REST frameworks such as JAX-RS. The entire platform is distributed as two JAR files totaling approximately 30KB in size, making it an ideal choice for applications where a minimal footprint is required.

This article introduces the HTTP-RPC server framework and provides an overview of its key features.

DispatcherServlet

DispatcherServlet is an abstract base class for REST services. Service operations are defined by adding public methods to a concrete service implementation.

Methods are invoked by submitting an HTTP request for a path associated with a servlet instance. Arguments are provided either via the query string or in the request body (like an HTML form), or as JSON. DispatcherServlet converts the request parameters to the expected argument types, invokes the method, and serializes the return value to the output stream as JSON.

The RequestMethod annotation is used to associate a service method with an HTTP verb such as GET or POST. The optional ResourcePath annotation can be used to associate the method with a specific path relative to the servlet. If unspecified, the method is associated with the servlet itself.

Multiple methods may be associated with the same verb and path. DispatcherServlet selects the best method to execute based on the provided argument values. For example, the following service class might be used to implement some simple mathematical operations:

@WebServlet(urlPatterns={"/math/*"})
public class MathServlet extends DispatcherServlet {
    @RequestMethod("GET")
    @ResourcePath("/sum")
    public double getSum(double a, double b) {
        return a + b;
    }

    @RequestMethod("GET")
    @ResourcePath("/sum")
    public double getSum(List values) {
        double total = 0;

        for (double value : values) {
            total += value;
        }

        return total;
    }
}

The following request would cause the first method to be invoked:

GET /math/sum?a=2&b=4

This request would invoke the second method:

GET /math/sum?values=1&values=2&values=3

In either case, the service would return the value 6 in response.

Method Arguments

Method arguments may be any of the following types:

• Numeric primitive or wrapper class (e.g. int or Integer)
• boolean or Boolean
• String
• java.util.List
• java.util.Map
• java.net.URL

List arguments represent either multi-value parameters submitted using one of the form encodings or array structures submitted as JSON. Map arguments represent object structures submitted as JSON, and must use strings for keys. List and map values are automatically converted to their declared types when possible.

URL arguments represent file uploads. They may be used only with POST requests submitted using the multi-part form data encoding. For example:

@WebServlet(urlPatterns={"/upload/*"})
@MultipartConfig
public class FileUploadServlet extends DispatcherServlet {
    @RequestMethod("POST")
    public void upload(URL file) throws IOException {
        ...
    }

    @RequestMethod("POST")
    public void upload(List files) throws IOException {
        ...
    }
}

Return Values

Return values are converted to their JSON equivalents as follows:

• Number: number
• Boolean: true/false
• CharSequence: string
• Iterable: array
• java.util.Map: object

Methods may also return void or Void to indicate that they do not produce a value.

For example, the following method would produce a JSON object containing three values. The mapOf() and entry() methods are provided by the framework to help simplify map creation:

@RequestMethod("GET")
public Map getMap() {
    return mapOf(
        entry("text", "Lorem ipsum"),
        entry("number", 123),
        entry("flag", true)
    );
}

The service would return the following in response:

{
    "text": "Lorem ipsum",
    "number": 123,
    "flag": true
}

Request and Response Properties

DispatcherServlet provides the following methods to allow a service to access the request and response objects associated with the current operation:

protected HttpServletRequest getRequest() { ... }
protected HttpServletResponse getResponse() { ... }

For example, a service might access the request to get the name of the current user, or use the response to return a custom header.

The response object can also be used to produce a custom result. If a service method commits the response by writing to the output stream, the return value (if any) will be ignored by DispatcherServlet. This allows a service to return content that cannot be easily represented as JSON, such as image data or alternative text formats.

Path Variables

Path variables may be specified by a "?" character in the resource path. For example:

@RequestMethod("GET")
@ResourcePath("/contacts/?/addresses/?")
public List<Map<String, ?>> getContactAddresses() { ... }

The getKeys() method returns the list of variables associated with the current request:

protected List<String> getKeys() { ... }

For example, given the following path:

/contacts/jsmith/addresses/home

getKeys() would return the following:

["jsmith", "home"]

Summary

HTTP-RPC is an open-source framework for simplifying development of REST applications. It provides a lightweight alternative to larger Java REST frameworks such as JAX-RS, making it an ideal choice for low-footprint applications such as microservices or IoT.

For more information, see the project README.