REST client

REST client module allows to make AJAX queries to REST services. It uses annotations from JAX-RS, which is a part of Java EE specification. There are several implementations of JAX-RS, like Jersey or CXF. This means that you can write full-stack application, reusing JAX-RS declarations both to declare REST services and use them from client code.

Getting started

Let’s start by creating a client for server-side math library. For now this library only supports addition of integer numbers. Suppose, someone has implemented server that accepts GET queries to address:

/api/math/integers/sum?a={number}&b={number}

and responds with integer number.

Let’s create definition for the service:

@Path("math")
public interface MathService {
    @GET
    @Path("integers/sum")
    int sum(@QueryParam("a") int a, @QueryParam("b") int b);
}

Now we need to create an instance of this interface. This is trivial:

MathService math = RESTClient.factory(MathService.class).createResource("api");

Now you can use this instance like this:

System.out.println(math.sum(2, 3));

By the way, if the author of the service implemented in Java, it would something like:

public class MathServiceImpl implements MathService {
    @Override
    public int sum(int a, int b) {
        return a + b;
    }
}

so, the whole thing looks like just calling MathServiceImpl.sum(). Writing JAX-RS services is out of scope this manual, and of scope of Flavour. There are many manuals and tutorials, you can hopefully find some. For example, you can read this one.

Supported JAX-RS subset

Flavour supports some reasonable subset of JAX-RS annotation. It does not implement JAX-RS client API, instead Flavour provides its own simple API.

Here is the list os supported JAX-RS annotations:

Currently, Flavour supports only JSON bodies.

Client API

REST client API has the following entry point:

ResourceFactory<T> RESTClient.factory(Class<T> type)

factory accepts type of service interface.

By calling ResourceFactory.createResource(String basePath) you get instance of corresponding service. basePath specifies location of a the service, it’s merely a string which will be used as a prefix to request address.

Additionally, you can call one of ResourceFactory.add methods to manually process all requests and responses. It can be useful in some use-cases, like adding security token to requests, perform additional error processing of return statuses, and so forth.


Improve this page