CategoryViewHandler (Search)

This class provides RESTful services to get category data for search-based catalog navigation. It performs the services on the WebSphere Commerce server.

Instead of using the /wcs/resources/store/ URI, the REST service URI must contain /search/resources/store/ under the default configuration.

The supported search profiles are identified at runtime according to the Search-REST/WEB-INF/config/com.ibm.commerce.rest/wc-rest-resourceconfig.xml file. For more information about the WebSphere Commerce search profiles, see WebSphere Commerce search profiles.

WebSphere Commerce search REST APIs

The REST classes that are denoted by (Search) in the title are applicable to the WebSphere Commerce search server.

They have the following benefits over the BOD-based REST services:

The services are served by the search server and can be separately scaled from the WebSphere Commerce server. Instead, the WebSphere Commerce server is used for processing transactional requests.
The WebSphere Commerce search REST API is built to extract data from Solr queries, avoiding the need for the BOD mediation layer.

Note: Attributes that are not managed by the Attribute Dictionary are not indexed or returned by default in search-based REST responses. You must either migrate your attributes to the Attribute Dictionary, or create a custom postprocessor to fetch the applicable attributes to catalog entries in the response, and then add them to the search-based REST response.


Method Name	HTTP Method	URL	Query Parameters	Description	Authentication	Example
findCategoryByUniqueId	GET	store/{storeId}/categoryview/byId/{categoryId}	checkEntitlement={checkEntitlement}	Gets category details based on its unique ID.	No,HTTP	Sample
findCategoryByUniqueIds	GET	store/{storeId}/categoryview/byIds	orderBy={orderBy}& id={categoryId}*& checkEntitlement={checkEntitlement}	Gets category details based on its unique ID.	No,HTTP	Sample
findCategoryByIdentifier	GET	store/{storeId}/categoryview/{categoryIdentifier}	categoryIdentifier={categoryIdentifier}	Gets category details based on its identifier.	No,HTTP	Sample
findTopCategories	GET	store/{storeId}/categoryview/@top?catalogId={catalogId}	depthAndLimit={listOfLimits}& pageNumber={pageNumber}& pageSize={pageSize}& orderBy={orderBy}& checkEntitlement={checkEntitlement}	Gets all the top level categories and optionally subcategories.	No,HTTP	Sample
findSubCategories	GET	store/{storeId}/categoryview/byParentCategory/{parentCategoryId}?catalogId={catalogId}	depthAndLimit={listOfLimits}& pageNumber={pageNumber}& pageSize={pageSize}& orderBy={orderBy}& checkEntitlement={checkEntitlement}	Gets child categories based on the parent category unique ID.	No,HTTP	Sample

Where the following Query Parameters are defined as:

id

The repeated value list of category IDs. For example, id=123&id=456.

pageSize

Mapped to _wcf.search.page.size. Returns up to the maximum number of items (immediate child categories) in the response.

All items will be returned if this parameter is not specified.

Note: This parameter is overriden by the maxRows property value of the IBM_findSubCategories search profile. If pageSize > maxRows, then the maxRows parameter value should be increased to at least the pageSize value. For more information, see WebSphere Commerce search profiles.

pageNumber

Mapped to _wcf.search.page.number. Returns results of the page number, starting from 1, if there are more results than the pageSize number.

This parameter is used with the pageSize parameter.

The default value is 1.

depthAndLimit {listOfLimits}

Mapped to _wcf.search.category.limitSubCategories. The comma separated list of numbers is to control the depth of subcategories and limit the number of items returned under each child category level. The first number in this list determines the maximum of categories (first-level subcategories) to be returned under the immediate child category. The second number in the list determines the maximum number of categories to be returned under the first-level subcategories. A value of -1 implies no limit, where only the first-level categories will be returned.

For example, pageSize=4&depthAndLimit=-1,3,0,1 implies that there will be unlimited first level subcategories under the immediate child categories. Under these categories (up to 4), all subcategories will be returned and a maximum of 3 second-level subcategories will be returned. There will be no third level or fourth level since the third level limit is 0. Any level after a limit of 0 will be ignored.

By default, no subcategory will be returned if this parameter is not specified.

When the asterisk (*) is specified, it is considered the same as -1 but, any subsequent levels will also be treated -1.

Note: The maxRows property in the IBM_findSubCategories search profile takes precedence over this parameter. If maxRows is set its value is used, rather than the value of depthAndLimit, to determine how many categories to return at each subcategory level. The IBM_findSubCategories search profile and maxRows property are set in the wc-search.xml configuration file. For more information, see WebSphere Commerce search profiles.

orderBy

Mapped to _wcs.search.sort:

1: Sort by brand/manufacturer name in ascending alphabetical order.
2: Sort by category name in ascending alphabetical order.
3: Sort by price in ascending order.
4: Sort by price in descending order.

These values are configurable in the WebSphere Commerce search configuration file. For more information, see WebSphere Commerce search configuration file (wc-search.xml) (Search EAR).

categoryIdentifier

The optional categoryIdentifier parameter that will replace the {categoryIdentifier} value in the context path parameter. It is used to avoid potential limitations of the special characters that are part of the context path.

checkEntitlement

The boolean flag to indicate whether to check entitlement of the caller. To check entitlement, the flag must be set to true.

The default value is false.

Note: JSON is the only response format supported by the WebSphere Commerce search CategoryViewHandler by default.

WebSphere Commerce search query parameters

The following query parameters are specific to the WebSphere Commerce search REST API, such as the CategoryViewHandler, ProductViewHandler, and SiteContentHandler resources.

profileName

An optional search profile name that can be specified. It must be listed under the Search-Rest/WEB-INF/config/com.ibm.commerce.rest/wc-rest-resourceconfig.xml configuration file for the resource that is being requested.

For example, for a service with the following URI:


<GetUri uri="store/{storeId}/categoryview/byId/{categoryId}"
description="Get category by unique ID"
searchProfile="IBM_findCategoryByUniqueIds,IBM_Admin_findCategoryByIds"/>

The IBM_Admin_findCategoryByIds search profile can be specified, while IBM_findCategoryByUniqueIds is the default search profile when the profileName is not specified.

responseTemplate

The structure of response that is being used.

A value of 0 generates BOD-like responses for the responsive Aurora starter store, while a value of 1 generates REST responses.

The default value is 0.

Field name mapping definitions are used to leverage different fields in responses. The mappings are divided into the following categories:

CatalogEntryView: Maps the catalog entry section inside the Product REST responses.
CatalogGroupView: Maps the category section inside the Category REST responses.
WebContentView: Maps the web content section inside the SiteContent REST responses.

The mappings are stored in the Search_eardir/xml/config/com.ibm.commerce.catalog/wc-component.xml file.