HTTP API Use Case Tutorial

This page is a tutorial on how to build a simple application with a custom HTTP API (using a request handler) involving a basic query transform (in a searcher) involving a shared component and a custom output format (a renderer). The tutorial code can be found in the http-api-using-searcher sample application. Also, it is useful to read the component types tutorial for the motivation in choice of component types.

Goal: process incoming request of the form

into search requests.

Request handler

The request handler converts the HTTP GET request into something suitable for a Vespa search. Refer to this selection of base classes to choose the correct starting point for the application. The @Inject annotation is not strictly necessary, but is included for clarity. Review the code in


The searcher does a structured query transform, i.e. adding a few custom terms programmatically to the query. Review the code in The searcher uses custom configuration, where the config definition is in demo.def:


demo[].term string
In other words, a configuration class containing a single array named demo, containing a class Demo which only contains single string named term.


The renderer serializes the structured result into bytes for transport back to the client. Note that rendering works by first creating a single instance of the renderer (invoking the constructor), then cloning a new renderer for each result set rendered. init() will be invoked once on each new clone before render() is invoked. Review the code in

Shared component

The custom component decouples some parts of the application from the searcher. This makes it possible to reconfigure the searcher without rebuilding the potentially costly custom component. In this case, what the component does is more than a little silly. More typical use would be an FSA or complex, shared helper functionality. Review the code in

Try it!

  • Review the configuration in services.xml and the schema in
  • Deploy the application (cd to vespa-engine/sample-apps/http-api-using-searcher/)
  • Feed test documents:
    $ java -jar $VESPA_HOME/lib/jars/vespa-http-client-jar-with-dependencies.jar --file feed.json --host localhost --port 8080
  • Query:
    $ curl 'http://localhost:8080/demo?extraTerm=something'