- v1.0.0-latest-prod
Catalog Services provides an endpoint to facilitate building category browse pages in as few requests to the Catalog APIs as possible. CategoryDetailsEndpoint is the entry-point for requests, and CategoryDetailsService is the place to start for customizing the response.
|
Tip
|
For minimizing calls including to other microservice APIs such as Pricing Services, consider using the CatalogBrowse microservice, which comes with an integration to the pricing engine already for category browse, product details, and search results pages. |
The CategoryDetailsEndpoint provides access to a Category and all data relevant to a category browse page. This includes its products (paginated), assets, and promotional products. It will also provide breadcrumbs based on its parent categories.
|
Tip
|
See the OpenAPI spec for the category details endpoint. |
categoryUrl: URL that maps to a specific category.
This is used if categoryId is not provided and is the typical way a category is identified by a commerce-facing app since the URL that a user has navigated to is available while the specific ID of the category is not.
categoryId: The specific ID of the category to retrieve
productPageInfo: Pagination info applied to the products retrieved along with the category
Any other parameters are automatically placed in an attributes map on the CategoryDetailsRequest DTO and be referenced in the business logic thereby.
The following diagram covers the overall response DTOs. Most of these DTOs are simply augmented versions of basic Catalog entities and shared fields were omitted in favor of focusing on what’s added.
CategoryDetails represents an augmented version of a Category that includes all the disparate relationships it has consolidated into one object.
It includes all of the fields of the base category.
It additionally includes:
assets: All of the category’s assets' metadata including their:
type: The asset type: IMAGE, VIDEO, PDF, etc.
altText: Corresponds to the HTML alt attribute on an <img> tag.
title: Corresponds to the HTML title attribute on an <img> tag.
contentUrl: The full URL used to resolve the actual asset content such as a CDN path for an image
embedCode: HTML to embed on a frontend.
tags: Additional, descriptive or identifying text.
See CategoryAsset javadocs for the full details.
breadcrumbs: List of navigational breadcrumbs based on the category’s request context or category hierarchy.
products: Hydrated page of products with summary information sufficient for displaying a category details or product list page.
A priceInfo DTO replaces the price fields, providing the target, best price, and some details about the other candidate prices.
promotionalProducts: Lists of the various kinds of promotional products such as featured mapped by their type.
|
Tip
|
See the CategoryDetails javadoc for further details. |
This service is responsible for retrieving CategoryDetails for CategoryDetailsRequests. It is responsible for building the details. By default, it defers the meat of the work to the CategoryDetailsContributors.
The process starts by building a CategoryDetailsContext. This facilitates gathering all of the related catalog entities to the requested category all at once to allow fewer calls to the database throughout the process. This is done by:
Gathering all of the context info using the CategoryDetailsContextContributors.
Then, consolidating it onto the related entities such as adding ProductAssets to the related Products using the CategoryDetailsContextConsolidators.
Once the context is setup, the CategoryDetailsContributors are invoked to actually populate the gathered data onto the CategoryDetails DTO.
Information required to build CategoryDetails for a commerce-facing category browse page. This contains important context information for determining which category to gather details for and, potentially, the extent of the details. Prior to building the details itself, this context is constructed to store all of the catalog entities related to the requested category to allow for as few calls to the database as possible. After this, the data is organized hierarchically as appropriate without needing additional database requests.
These services are responsible for contributing a specific subset of information to a CategoryDetailsContext based on a CategoryDetailsRequest in order to retrieve all related entities in bulk operations rather than piece-meal for performance reasons. It is desirable for implementations of this class to be as narrow as possible in the breadth of their contributions to improve extensibility, re-usability, testability, and readability.
|
Important
|
Contributors should handle all the DB queries necessary for gathering all the related entities while consolidation (such as merging product assets onto related products) should be handled byCategoryDetailsContextConsolidators as consolidators will run after all contributors. |
RelatedProductsCategoryContextContributor: Contributes all of the related Products to the CategoryDetailsContext.
RelatedVariantsCategoryContextContributor: Contributes all of the related Variants to the CategoryDetailsContext.
This will look for direct variants of the related products.
This should be run after RelatedProductsCategoryContextContributor to allow us to gather all the variants at once.
Extend #contributeOtherVariantIds to contribute other variant IDs before fetching all of the related variants.
RelatedProductTagsCategoryContextContributor: Contributes all of the related ProductTags for the products.
This will hydrate the AdvancedTags onto the ProductTags.
This also filters out automatically any inactive ProductTag or ProductTags related to inactive AdvancedTags.
RelatedProductAssetsCategoryContextContributor: Contributes all of the related ProductAssets to the CategoryDetailsContext.
This should be run after RelatedProductsCategoryContextContributor to allow us to gather all the assets at once.
RelatedCategoryAssetsCategoryContextContributor: Contributes all of the related CategoryAssets] to the CategoryDetailsContext.
These services handle consolidating context information provided by CategoryDetailsContextContributors as needed.
|
Important
|
CategoryDetailsContextContributors should handle any necessary DB queries to gather the related entities while contributors merge the data together before they are contributed to a CategoryDetails. |
RelatedVariantsCategoryContextConsolidator: Consolidates all of the context info for related variants onto those variants.
RelatedProductsCategoryContextConsolidator: Consolidates all of the context info for related products onto those products.
RelatedPromotionalProductsCategoryContextConsolidator: Consolidates all of the context info for related promotional products onto those products.
These services are responsible for contributing a specific subset of information to a CategoryDetails based on a CategoryDetailsContext such as contributing the assets or contributing the breadcrumbs. It is desirable for implementations of this class to be as narrow as possible in the breadth of their contributions to improve extensibility, re-usability, testability, and readability. This also provides a simple means of adding in additional augmentations to the CategoryDetails response by registering a new contributor.
ProductsCategoryDetailsContributor: Contributes the requested category’s products.
CategoryAssetsCategoryDetailsContributor: Contributes the requested category’s assets.
BreadcrumbsCategoryDetailsContributor: This contributor is responsible for the CategoryDetails' breadcrumbs
RelatedPromotionalProductsCategoryDetailsContributor: Contributes the requested category’s promotional products