Response filters
Response filters provide an alternative way to use the
fields
and exclude
query parameters.
This section applies to Open Storefront Framework (OSF) and Storefront Classic.
fields
or exclude
to explicitly list properties in the URL of a REST call, you can create persistent filters that store the set of properties to include or exclude. You can then specify a filter by name in the URL using the filterKey
query parameter. For example, you could create a response filter named productSummary
that lists product properties to include, and then invoke the filter like this:GET /ccadmin/v1/products?filterKey=productSummary
Note:A response filter is essentially a wrapper for the fields
and exclude
query parameters, and the properties returned by a filter are the same as they would be for equivalent fields
and exclude
expressions. If you include the filterKey
query parameter and either fields
or exclude
(or both) in an API call, filterKey
is ignored, and fields
and exclude
are applied.
listFilters
endpoint in the Admin API:GET /ccadmin/v1/responseFilters HTTP/1.1
Authorization: Bearer <access_token>
{
"links": [
{
"rel": "self",
"href": "http://myserver.example.com:7002/ccadmin/v1/responseFilters"
}
],
"items": [
{
"include": "items.id,items.displayName,items.type,items.variantValuesOrder,
items.productVariantOptions,items.defaultProductListingSku,
items.dynamicPropertyMapLong,items.route,items.primarySmallImageURL,
items.primaryImageAltText,items.primaryImageTitle,items.childSKUs,
items.listPrice,items.salePrice,items.relatedProducts,
category.displayName,items.description,totalResults,offset,
totalExpandedResults",
"exclude": "items.childSKUs.largeImage,items.childSKUs.largeImageURLs,
items.childSKUs.fullImageURLs,items.childSKUs.listPrices,
items.childSKUs.mediumImageURLs,items.childSKUs.primaryLargeImageURL,
items.childSKUs.primaryMediumImageURL,
items.childSKUs.primaryThumbImageURL,items.childSKUs.thumbImageURLs,
items.childSKUs.salePrices,items.childSKUs.thumbnailImage,
items.childSKUs.barcode,items.childSKUs.denomination,
items.childSKUs.model,items.childSKUs.productFamily,
items.childSKUs.productLine,items.childSKUs.unitOfMeasure,
items.childSKUs.saleVolumePrices",
"key": "PLPData"
},
{
"include": "childCategories(items).displayName,childCategories(items).route,
childCategories(items).id,
childCategories(items).childCategories.displayName,
childCategories(items).childCategories.route,
childCategories(items).childCategories.id,
childCategories(items).childCategories.childCategories.displayName,
childCategories(items).childCategories.childCategories.route,
childCategories(items).childCategories.childCategories.id,
childCategories(items).childCategories.childCategories.childCategories",
"key": "categoryNavData"
},
{
"include": "items.id,items.displayName,items.productVariantOptions,
items.defaultProductListingSku,items.dynamicPropertyMapLong,
items.route,items.primarySmallImageURL,items.primaryImageAltText,
items.primaryImageTitle,items.childSKUs.listPrice,
items.childSKUs.salePrice,items.listPrice,items.salePrice,
items.relatedProducts,items.childSKUs.dynamicPropertyMapLong,
items.childSKUs.repositoryId,category.displayName,items.description",
"key": "collectionData"
},
{
"include": "id,active,saleVolumePrices,listVolumePrices,route,configurable,
dynamicPropertyMapLong,productVariantOptions,primaryThumbImageURL,
notForIndividualSale,displayName,childSKUs.repositoryId,
childSKUs.active,childSKUs.listPrice,childSKUs.salePrice,
childSKUs.primaryThumbImageURL,childSKUs.listingSKUId,
childSKUs.saleVolumePrices,childSKUs.listVolumePrices,
childSKUs.dynamicPropertyMapLong",
"key": "productData"
}
]
}
Each filter must have a key
(which is used to identify the filter), and either an include
array (equivalent to the fields
query parameter) an exclude
array (equivalent to the exclude
query parameter), or both.
getFilter
endpoint. For example:GET /ccadmin/v1/responseFilters/productData HTTP/1.1
Authorization: Bearer <access_token>
Note that you should not modify or delete the default response filters, as they are used by widgets provided with Commerce, and these widgets may not work properly if the response filters are changed. For information about these response filters and how they are used by widgets, see Filter REST Responses.
Create response filters
createFilter
endpoint. For example, the following call creates a new response filter named productLabels
:POST /ccadmin/v1/responseFilters HTTP/1.1
Authorization: Bearer <access_token>
{
"key": "productLabels",
"include": "items.id,items.displayName,items.description"
}
productLabels
filter to restrict the set of properties returned for products:GET /ccadmin/v1/products?filterKey=productLabels HTTP/1.1
Authorization: Bearer <access_token>
"items": [
{
"displayName": "A-Line Skirt",
"description": "The simple perfect A line",
"id": "xprod2535"
},
{
"displayName": "Acadia Wood Chair",
"description": "Craftsman meets classic in this attractive wood chair",
"id": "xprod2148"
},
{
"displayName": "Americana Nightstand",
"description": "Classic American design",
"id": "xprod2103"
},
...
]
}
Modify response filters
updateFilter
endpoint to modify response filters. For example, the following call changes the set of properties returned by the productLabels
filter shown above:PUT /ccadmin/v1/responseFilters/productLabels HTTP/1.1
Authorization: Bearer <access_token>
{
"include": "items.displayName,items.description,items.listPrice"
}
Note that when you modify a response filter, the changes to the filter do not take effect until your JSON cache is cleared. This cache is cleared each time you publish changes on your Commerce instance. Changes to response filters themselves do not require publishing, so to force the cache to be cleared, you need to modify a publishable asset (such as an item in the product catalog) and then invoke publishing.
Delete response filters
deleteFilter
endpoint to delete a response filter. For example:DELETE /ccadmin/v1/responseFilters/productLabels HTTP/1.1
Authorization: Bearer <access_token>