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
http://hostname:8080/demo?extraTerm=somethinginto search requests.
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.
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 stringIn 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
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
- 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
$ curl 'http://localhost:8080/demo?extraTerm=something'