Rest handlers example

In this article, you will learn how to apply parameters to a REST DataDescriptor, as well as how to use one. In this example, a public Rest API will be used. This is the Open Movie Database ( https://www.omdbapi.com/ ). It is a free, public movie database. You can search for movies by their title. It also stores details about the movies, such as the cast, the IMDB rating, etc.

To start, you must request a free API key here: https://www.omdbapi.com/apikey.aspx After filling out the form, you will recieve your API key shortly. This key can be tested in your browser: https://www.omdbapi.com/?apikey=<YOUR PERSONAL APIKEY>&s=Heaven

This will return the first 10 movies from the database, that have "Heaven" in their title.

In this article, we will use two Rest services, one for movie searching, and one for downloading the details about the selected movie.

We will use the following two DataDescriptors:

  Example RestDataDescriptor for searching  
         
<datadescriptor name="OmdbRestDD" connectorType="REST">
	<access>
		<type>Public</type>
	</access>
	
	<params>
		<param name="endpoint">http://www.omdbapi.com</param>
		<param name="basePath"></param>
		<param name="mediaType">application/json</param>
		<param name="timeout">5000</param>
		<param name="filterHandler">com.company.rest.dd.handler.omdb.FilterHandler</param>
		<param name="paginationHandler">com.company.rest.dd.handler.omdb.PaginationHandler</param>
		<param name="responseHandler">com.company.rest.dd.handler.omdb.ResponseHandler</param>
		<param name="find.path">/?apikey=INSERT YOUR APIKEY HERE</param>
		<param name="find.pageParamName">page</param>
		<param name="find.filterParamName">s</param>
	</params>
	
	<column name="imdbID" datatype="VARCHAR2" primaryKey="true" length="15" filterable="false" />
	<column name="Title" datatype="VARCHAR2" length="255" />
	<column name="Type" datatype="VARCHAR2" length="10" filterable="false" />
	<column name="Year" datatype="VARCHAR2" length="4" filterable="false" />
	<column name="Poster" datatype="VARCHAR2" length="255" filterable="false" />
</datadescriptor>

  Example RestDataDescriptor to show details of the selected movie  
         
<datadescriptor name="OmdbDetailsRestDD" connectorType="REST">
	<access>
		<type>Public</type>
	</access>
	
	<params>
		<param name="endpoint">http://www.omdbapi.com</param>
		<param name="basePath"></param>
		<param name="mediaType">application/json</param>
		<param name="timeout">5000</param>
		<param name="filterHandler">com.company.rest.dd.handler.omdb.FilterDetailsHandler</param>
		<param name="responseHandler">com.company.rest.dd.handler.omdb.DetailsResponseHandler</param>
		<param name="find.path">/?apikey=INSERT YOUR APIKEY HERE</param>
		<param name="find.filterParamName">i</param>
	</params>
	
	<column name="imdbID" datatype="VARCHAR2" primaryKey="true" length="15" filterable="false" />
	<column name="Title" datatype="VARCHAR2" length="255" />
	<column name="Genre" datatype="VARCHAR2" length="40" filterable="false" />
	<column name="Type" datatype="VARCHAR2" length="10" filterable="false" />
	<column name="Year" datatype="VARCHAR2" length="4" filterable="false" />
	<column name="Director" datatype="VARCHAR2" length="80" filterable="false" />
	<column name="Actors" datatype="VARCHAR2" length="255" filterable="false" />
	<column name="Country" datatype="VARCHAR2" length="50" filterable="false" />
	<column name="imdbRating" datatype="VARCHAR2" length="5" filterable="false" />
	<column name="Plot" datatype="VARCHAR2" length="4000" filterable="false" />
</datadescriptor>

How to access the parameters specified in the DataDescriptor (this will be needed when implementing the handler classes):

  Get a DataDescriptor parameter  
         
String parameterValue = RestUtil.getDDParam(dd, RestParams.ENDPOINT);

You can find the parameters that can be specified and queried in the RestParams enum

We have specified the handler classes in the DataDescriptors. These implement the filtering, pagination (page fetching), and processing of the response. The handler classes only need to be specified and implemented, if the Rest service supports the specified functions. For example, if the Rest server does not support the Order operation, you do not have to specify the orderHandler. The responseHandler does not need to be specified, if the response is a standard JSON in a JSON array.

  Pure JSon array - not need to define custom ResponseHandler  
         
[
  	{
		"firstName": "John",
		"lastName": "Walsh",
		"Birth": "02.12.1985"
	},
	{
		"firstName": "Anne",
		"lastName": "Lee",
		"Birth": "19.10.1989"
	}
]

Here, neither response is a JSON array, so the responseHandler must be implemented.

  FilterHandler to search film in Open Movie DB  
         
package com.company.rest.dd.handler.omdb;

import java.util.Arrays;
import java.util.List;
import java.util.StringJoiner;

import com.jbstrap.core.dao.Criteria;
import com.jbstrap.rest.dd.RestDataDescriptor;
import com.jbstrap.rest.dd.handler.JBFilterHandler;
import com.jbstrap.rest.dd.param.RestParams;
import com.jbstrap.rest.util.RestUtil;

public class FilterHandler implements JBFilterHandler {
	
	@Override
	public String handle(RestDataDescriptor dd, Criteria criteria) {
		if (criteria == null) {
			return null;
		}
		
		StringJoiner sj = new StringJoiner("+");
	
		List<Criteria> criteriaList = getSimpleCriteriaList(criteria);
		criteriaList.forEach(c -> sj.add(c.getValue().toString()));

		return RestUtil.getDDParam(dd, RestParams.FIND_FILTER_PARAM_NAME) + "=" + sj.toString();
	}
	
	private List<Criteria> getSimpleCriteriaList(Criteria criteria) {
		if (criteria.isComplex()) {
			if (criteria.getSubCriteria().get(0).isComplex()) {
				return getSimpleCriteriaList(criteria.getSubCriteria().get(0));
			} else {
				return criteria.getSubCriteria();
			}
		}
		return Arrays.asList(criteria);
	}
}

  Pagination in Open Movie DB  
         
package com.company.rest.dd.handler.omdb;

import com.jbstrap.rest.dd.RestDataDescriptor;
import com.jbstrap.rest.dd.handler.JBPaginationHandler;
import com.jbstrap.rest.dd.param.RestParams;
import com.jbstrap.rest.dd.service.type.RestType;
import com.jbstrap.rest.util.RestUtil;

public class PaginationHandler implements JBPaginationHandler {

	@Override
	public String handle(RestType restType, RestDataDescriptor dd, int startRow, int endRow) {
		
		// page index starts from 1 (not 0!)
		// e.g: http://www.omdbapi.com/?apikey=xxxxx&s=Heaven&page=1
		
		// add page param
		return RestUtil.getDDParam(dd, RestParams.FIND_PAGE_PARAM_NAME) + "=" + (endRow / 10);
	}

}

  ResponseHandler implementation  
         
package com.company.rest.dd.handler.omdb;

import java.util.List;

import org.apache.http.Header;
import org.apache.http.StatusLine;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.jbstrap.core.dao.DataRecord;
import com.jbstrap.rest.dd.RestDataDescriptor;
import com.jbstrap.rest.dd.handler.JBResponseHandler;
import com.jbstrap.rest.dd.service.type.RestType;
import com.jbstrap.rest.exception.RestException;
import com.jbstrap.rest.util.RestUtil;

/**
 * Custom handler for Rest response.
 * 
 * example response:
 * 
 * {
 * "Search": [
 *   {
 *     "Title": "Heaven Help Us",
 *     "Year": "1985",
 *     "imdbID": "tt0089264",
 *     "Type": "movie",
 *     "Poster": "https://m.media-amazon.com/images/M/MV5BMzZiNDM2YzItOTVlMS00ZTg5LWE0ZDMtYmI5M2NmOWE0ZGU4XkEyXkFqcGdeQXVyMjUzOTY1NTc@._V1_SX300.jpg"
 *   },
 *   {
 *     "Title": "Heaven Can Help",
 *     "Year": "1984",
 *     "imdbID": "tt0088096",
 *     "Type": "movie",
 *     "Poster": "https://m.media-amazon.com/images/M/MV5BMTI4NTg2ODM1NF5BMl5BanBnXkFtZTcwMjE3MDAyMQ@@._V1_SX300.jpg"
 *   }
 * ],
 * "totalResults": "2",
 * "Response": "True"
 * }
 * 
 * In case of error:
 * 
 * {
 *   "Response": "False",
 *   "Error": "Movie not found!"
 * }
 */
@SuppressWarnings("unchecked")
public class ResponseHandler implements JBResponseHandler {
	private static final Logger LOG = LoggerFactory.getLogger(ResponseHandler.class);

	@Override
	public List<DataRecord> handleResponse(RestType restType, RestDataDescriptor dd, String jsonResult, Header[] headers, StatusLine statusLine) throws RestException {
		int statusCode = statusLine.getStatusCode();
    	if (statusCode != 200) {
    		LOG.error("Rest status code is not 200/OK! Status code: " + statusCode);
    		throw new RestException("Rest status code is not 200/OK! Status code: " + statusCode);
    	}
		
		if (jsonResult != null) {
			List<DataRecord> resultList = RestUtil.jsonToRecords(jsonResult);
			
			if (resultList.size() == 1 && resultList.get(0).getValue("Search") != null) {
				// ok
				return (List<DataRecord>) resultList.get(0).getValue("Search");
			} else {
				// standard error
				String errorMsg = resultList.get(0).getValueAsString("Error");
				throw new RestException(errorMsg);
			}
		} else {
			// no valid error message
			throw new RestException("Unknown error!");
		}
	}
}