You create a Limberest service by implementing the Service interface. The easy way to do this is to extend a base implementation, probably JsonRestService. The base implementation ordinarily takes care of request object binding.

You declare service endpoints using JAX-RS @Path annotations. Here’s how this looks for the MoviesService in limberest-demo:

public class MoviesService extends JsonRestService {

This registers MoviesService to respond to requests for /movies resources. When a request is received by Limberest, it’s forwarded to the service with the most specific matching registered path (for example: a request to /movies/a2d7721c will invoke the service registered with path “/movies/{id}” in preference to that with just “/movies”).


The job of your service is to interpret the request and build a corresponding response. Here’s the complete get() method from MoviesService:

    public Response<JSONObject> get(Request<JSONObject> request) throws ServiceException {
        List<Movie> movies = getPersist().retrieve(request.getQuery());
        JsonList<Movie> jsonList = new JsonList<>(movies, "movies");
        return new Response<>(jsonList.toJson());

Let’s take a look at each step in this code:

  1. We invoke validate(), passing the Request. Validation may throw a ServiceException with an appropriate Status Code if it does not like the request. This mechanism is discussed in more detail in the Validation topic.
  2. Next we populate a List of movies by retrieving from a persistent store. Filtering of results is governed by HTTP query parameters that may be appended to the resource URL (e.g. ?sort=title). These are accessible via request.getQuery(), which returns a Limberest Query object. Check out the Queries topic to see how Limberest facilitates results filtering through HTTP query parameters.
  3. The retrieved list is made Jsonable by way of the JsonList utility class. Jsonables are the easiest way to accomplish JSON data binding in Limberest. In limberest-demo, the Movie model object implements Jsonable to take advantage of Limberest’s built-in Binding facility.
  4. Lastly, a Response is contructed from the retrieved Movies list and returned to the caller.

Source code for limberest-demo is available in its GitHub repository. Also, the Movies service is deployed on the Limberest site, so you can access the example services and try them out for yourself:

Note: The default root path for limberest services is /api/. See the Configuration topic for details on how to override this default.

Next Topic: Binding