Developing Web Service Applications

This document explains how to develop (REST) web service type applications on the container - design options, accessing the request path, returning a status code etc. There are two types of web service APIs:

  • Fine-grained APIs with closed semantics – for example return the number of stars of an article
  • Coarse-grained APIs with open semantics – for example return a page containing the most relevant mixture of stuff for this user and action
With fine-grained APIs, the container can help map the various requests to method calls through exposing an implementation of JAX-RS(Jersey). With coarse-grained APIs, it can help dealing with the complexity typically involved in the implementation of such APIs by providing a way to compose and federate components contributing to processing the request and provide and modify the returned data, and a way to allow such requests to start returning before they are finished to reduce latency with large responses. This is the processing framework (or, in the case of search-like application, the searcher specialization).

In addition, the container features a generic mechanism which allows a Handler component to be bound to a URL and invoked to handle all requests matching that URL. This is useful where there is neither a large fine-grained API nor any need to handle complexity and/or federation of various kinds of data in the response. Both the approaches above are implemented as provided Handlers.

A custom Handler may be written to parse the url path/method and dispatch to an appropriate chain of processing components. A "main" processing chain may be written to do the same by dispatching to other chains.

The simplest way to invoke a specific chain of processors is to forward a query to the ProcessingHandler with the request property chain set to the name of the chain to invoke:


public class DemoHandler extends {


    public DemoHandler(Executor executor, ProcessingHandler processingHandler) {
        this.processingHandler = processingHandler;


    public HttpResponse handle(HttpRequest request) {
        HttpRequest processingRequest = new HttpRequest.Builder(request)
                .put(, "theProcessingChainIWant")
        HttpResponse r = processingHandler.handle(processingRequest);
        return r;



Accessing the HTTP request

In a general JDisc request handler the can be cast to an instance of when the request is over HTTP. Web service handlers should usually extend (or the subclass which also does access logging), which provides to subclasses a which contains both the core HttpRequest and the associated properties and request data.

In Processing, one is given a which contains the HTTP URL parameters as well as the entire container request as a member variables. So to access the HttpRequest data in Processing, use:

// url parameters are added to properties
String urlParameter ="urlParameterName");

// jdisc request context is added with prefix context
Object contextValue ="context.contextKey");

// or, to access path, HTTP method or data, get the whole HTTP request: httpRequest =
// Then POST data inputstream would be:
InputStream in = httpRequest.getData();
// And the HTTP method:
Method method = httpRequest.getMethod();

Setting the HTTP status and HTTP headers

In Processing, the return status can be set by adding a special Data item to the Response:, request));
If no such data element is present, the status will be determined by the container. If it contains renderable data it will be 200, otherwise it will be determined by any ErrorMessage present in the response.

Setting response headers from Processors

Response headers may be added to any Response by adding instances of to the Response (ResponseHeaders is a kind of response Data). Multiple instances of this may be added to the Response, and the complete set of headers returned is the superset of all such objects. Example Processor:, request));
Request handlers may in general set their return status, and manipulate headers directly on the HttpRequest.


Sometimes all that is needed is letting the standard query framework reply for more paths than standard. This is possible by adding extra bindings inside the <search> element in services.xml. Writing a custom request handler is recommended if the application is a standalone HTTP API, and especially if there are properties used with the same name as those in the Query API. A request handler may query the search components running in the same container without any appreciable overhead:

Invoking Vespa queries from a component

To invoke Vespa queries from a component, have an instance of injected in your constructor and use its API to construct and issue the query. The container this runs in must include the <search> tag for the ExecutionFactory to be available. Example:


public class MyComponent {

    private final ExecutionFactory executionFactory;

    public MyComponent(ExecutionFactory executionFactory) {
        this.executionFactory = executionFactory;

    Result executeQuery(Query query, String chainId) {
        Chain<Search> searchChain = executionFactory.searchChainRegistry().getChain(new ComponentId(chainId));
        Execution execution = executionFactory.newExecution(searchChain);