HTTP API use-case

A tutorial in 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). Use the sample application found in http-api-using-searcher. Also, it is useful to read the component types tutorial for motivation in choice of component types.

Goal: process incoming request of the form

http://hostname:8080/demo?extraTerm=something
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 DemoHandler.java.

Searcher

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

package=com.mydomain.demo

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.

Renderer

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 DemoRenderer.java

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 DemoComponent.java

Try it!

  • Review the configuration in services.xml and the search definition in basic.sd.
  • 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'