Developing an API V2 search request response transformer

Help

Introduction

The API V2 search request response transformer provides a functionality that allows you to transform API V2 search requests and responses into a format that you can define yourself. This functionality is made available by the creation of a plugin with the Mindbreeze Software Development Toolkit. The SDK creates a sample plugin that can be customized.

Preparation

The following software components are needed to build and create a plugin with the Mindbreeze Software Development Toolkit:

• Java SE Development Kit: Version 1.8 or newer
• Eclipse IDE for Java developers

Creating a Mindbreeze plugin project

The Mindbreeze Software Development Toolkit contains a tool for generating a plugin project. The tool is provided as mesjavaplugin.bat for Microsoft Windows and as mesjavaplugin.sh for Linux.

Mindbreeze Software Development Toolkit

To create a plugin project for an API V2 Search Request Transformer plugin, the tool has to be opened using the following parameters:

mesjavaplugin.<sh|bat> <Plugin Type> <Name> <Base Package>

• Plugin type: The plugin type has to be searchtransformer.
• Name: You can choose any name you’d like for the plugin. In the configuration of the client service, the plugin can be selected using the name provided.
• Base package: The base package of the Java classes that are created. Can be freely chosen.

Creating a plugin

The Mindbreeze Software Development Toolkit creates a plugin project that is available in the current directory under the name provided.

1. Import a plugin project in Eclipse
   
   
2. A basic implementation of the plugin is available under the name <Name>APIV2SearchRequestResponseTransformerService.java.
   
3. To create the plugin, build.bat (Microsoft Windows) or build.sh (Linux) has to be executed. A plugin with the name
   <name>-searchtransformer.zip is generated.
   
4. The plugin can be installed with the Mindbreeze configuration interface.
   
5. In order to use the plugin, it has to be configured in the client service configuration. In this example an API V2 search request response transformer with the name APIV2SearchRequestResponseTransformer.MyCustomTransformer is configured. In order to get the metadata extension, mes:key, category, categoryinstance and icon in the result, they were configured as additional metadata. The parameter source specifies whether the value or the HTML representation is used.
   
   
6. The plugin can be called up using the URL https://clientservice:clientserviceport/plugin/ID/search?params. In this example, the ID would be APIV2SearchRequestResponseTransformer.MyCustomTransformer. The sample plugin that was created is called up using the URL https://clientservice:clientserviceport/plugin/ID/search?q=ALL&num=20. This URL performs a search for ALL and returns 20 results in XML format.

Implementing the transformation

Implementing the request transformation

In order to transform the request, the method transformRequest has to be implemented.

This example is included in the generated code of the SDK and transforms the search request, defined by the HTTP parameters q and num into a Mindbreeze search request. The metadata from the plugin configuration is requested in the Mindbreeze search request in order to be present in the result.

Implementing the response transformation

The response transformation is performed in the method transformResponse.

transformResponse(RpcController controller, ResponseTransformationRequest request, RpcCallback<HTTPResponse> done)

The request parameter contains the request to be transformed.  The response can be set using the parameter done. The following example writes all titles of the query response as text to the response.

The HTTP content type is determined by defining the MediaType in the response.