GraphSearch Plugin API Documentation

GraphSearch works with three different types of search and storage backends: RDF database, and Elasticsearch. Depending on the backend plugins need to implement their behaviors differently. Accordingly, a custom plugin has to implement one of the following interfaces for the target backend:

They all define one abstract method

getRecommendedDocuments(DocumentRecommendationRequest request, SearchSpaceProvider searchSpaceProvider)

with different types of return values due to differences in data structure. This is the key method a plugin needs to implement since it handles recommendation requests initiated from the client side.

Additionally, all three interfaces inherits a super interface

biz.poolparty.graphsearch.plugins.GenericPlugin

which defines the following 4 abstract methods

A custom plugin has to implement the aforementioned one interface and five abstract methods.

Altogether they control the activation of the plugin based on three dimensions seed resource, priority and search space.

getRecommendedDocuments

The core abstract method getRecommendedDocuments is the entrypoint of a plugin. When a client initiates a request, GraphSearch will dispatch the request and the search space configurations to this method as arguments. The custom recommendation algorithm of the plugin needs to be invoked by this method to process the request. Finally, the results need to be returned as return value of the method, which will be further formulated by GraphSearch as JSON response to the client.

The method expects three types of return values depending on the interface, i.e., the target backend of the plugin. The relationship is explained in the following table:

getName

The return value of this method will become the name of a plugin. This name will be used not only for the display caption of the plugin in the UI, but also an identifier uniquely defining the plugin. When a client issues a request to the plugin API endpoint, the request must include such a plugin name to specify the plugin which should handle the request.

getOrder

The return value of this method indicates the order or priority of a plugin in the cases that multiple plugins are available. The higher the value, the higher the priority of the plugin. The plugin with the highest order will be used as the default plugin for a search space in GraphSearch UI and recommendation API requests when the plugin is not specified.

getSearchSpaceId

This method implements a restriction that a plugin is enabled only for a specific search space identified by the search space ID as return value. If the plugin should be available to

canHandle

The return value of this method decides if a plugin can provide recommendations based on the reference resource and configuration of the search space provided as input arguments of the method. Typically, the implementation can always return true so that recommendation is always executed, regardless of whether the operation is meaningful or not. Certainly, depending on the actual requirements, more and finer grained conditions can be implemented in this method so that the recommendation logic proceeds only when reference resources and search spaces have certain characteristics.

if (recommendationPlugin.canHandle(documentId, searchSpaceProvider) 
  && (recommendationPlugin.getSearchSpaceId() == null 
    || searchSpaceId.equals(recommendationPlugin.getSearchSpaceId())))

The following classes encapsulate input and output data of the plugin API. They are all implemented as standard beans with getter and setter methods.

DocumentRecommendationRequest

Argument request of method getRecommendedDocuments is an instance of class biz.poolparty.graphsearch.web.recommendation.DocumentRecommendationRequest. It packages the parameters of HTTP requests from the client, detailed as follows:

SearchSpaceProvider

Argument searchSpaceProvider of method getRecommendedDocuments and canHandle is an instance of class biz.poolparty.graphsearch.plugins.SearchSpaceProvider<T>. It packages some configuration of the search space relevant to the recommendation process.

ProposalResult

A list of instances of class ProposalResult is the expected return value of method getRecommendedDocuments for plugins implementing interface SparqlRecommendationPlugin, i.e., plugins for RDF database backends. This class describes the structure of a recommendation result. Since the search data is RDF in this case, the required information is rather minimal, only the URI of the suggested resource and a score to rank all results.