Query service API specifications
The Query service uses a REST API for command and communications. There are two specifications you can use: the Version 2 API intended for use with the React storefronts; and a Version 1 spec designed for backward compatibility.
In this document
The Query service Swagger reference
A Swagger interface to the Query service endpoints is available in the Query REST API. You can use the Swagger as a quick reference to the API and its parameters. In this document the details and logic of the API are explored in a little more detail.
Version 2 storefront APIs
When you explore the Query REST API you will find that some of the classes are prefixed with "V2." These are API calls that are specific to the React storefronts. They do not apply to the Aurora-based stores. The classes that are not prefixed with "V2" are Version 1 calls.
The Version 2 APIs combine functionality from a number of separate Version 1 classes. The following table provides links to specifications and samples for each V2 class. The table gives each API name, which Version 1 endpoints it includes, and a list of parameters that can be used with it. Each parameter can support multiple values.
Type | V1 API endpoint URL | V2 API endpoint URL | V2 API parameters | Examples |
---|---|---|---|---|
Categories |
/search/resources/store/{id}/categoryview/{categoryIdentifier} /search/resources/store/{id}/categoryview/@top /search/resources/store/{id}/categoryview/byId/{categoryId} /search/resources/store/{id}/categoryview/byIdentifiers /search/resources/store/{id}/categoryview/byIds /search/resources/store/{id}/categoryview/byParentCategory/{parentCategoryId} |
/search/resources/api/v2/categories | Required:
Optional:
|
|
Products |
/search/resources/store/{id}/productview/{partNumber} /search/resources/store/{id}/productview/byCategory/{categoryId} /search/resources/store/{id}/productview/byId/{productId} /search/resources/store/{id}/productview/byIds /search/resources/store/{id}/productview/byPartNumber/{partNumber} |
/search/resources/api/v2/products | Required:
Optional:
|
|
SEO URL |
/search/resources/store/{id}/sitecontent/categorySuggestions /search/resources/store/{id}/sitecontent/keywordSuggestionsByTerm/{term} |
/search/resources/api/v2/urls | Required:
Optional:
Note: This endpoint does not support faceting,
sorting, or paging; this is simply a lookup by identifier
service. |
React API examples
- Categories example 1
- Request
URL:
Or,GET /api/v2/categories?storeId=1&identifier=Apparel or GET /api/v2/categories?storeId=1&identifier=Women%20Shirts%20Blouses,Dresses,Apparel v1 equivalent: /search/resources/store/{id}/categoryview/{categoryIdentifier} /search/resources/store/{id}/categoryview/byIdentifiers
Request header:GET /api/v2/categories?storeId=1&id=10002 or GET /api/v2/categories?storeId=1&id=10002,10001,1 v1 equivalent: /search/resources/store/{id}/categoryview/byId/{categoryId} /search/resources/store/{id}/categoryview/byIds
Response body:accept: application/json
{ "contents": [ { "id": "10001", "name": "Dresses", "identifier": "Dresses", "description": "Dresses", "thumbnail": "images/catalog/apparel/women/category/catr_wcl_dresses.png", "seo": { "href": "/shop/apparel/women/dresses" }, "links": { "self": { "href": "/api/v2/categories?storeId=1&id=10001" }, "parent": { "href": "/api/v2/categories?storeId=1&id=3" } } }, { "id": "10002", "name": "Blouses", "identifier": "Women Shirts Blouses", "description": "Blouses", "thumbnail": "images/catalog/apparel/women/category/catr_wcl_blouses.png", "seo": { "href": "/shop/apparel/women/blouses" }, "links": { "self": { "href": "/api/v2/categories?storeId=1&id=10002" }, "parent": { "href": "/api/v2/categories?storeId=1&id=3" } } }, { "id": "1", "name": "Apparel", "identifier": "Apparel", "description": "The latest styles for the entire family.", "thumbnail": "images/catalog/apparel/women/category/catr_wcl_pants.png", "seo": { "href": "/shop/apparel" }, "links": { "self": { "href": "/api/v2/categories?storeId=1&id=1" }, "children": [ { "href": "/api/v2/categories?storeId=1&id=2" }, { "href": "/api/v2/categories?storeId=1&id=3" }, { "href": "/api/v2/categories?storeId=1&id=4" }, { "href": "/api/v2/categories?storeId=1&id=5" } ] } } ] }
- Categories example 2
- Request
URL:
Request header:GET /api/v2/categories?storeId=1&depthAndLimit=-1,-1 v1 equivalent: /search/resources/store/{id}/categoryview/@top
Response body:accept: application/json
Response header:{ "contents": [ { "id": "1", "name": "Apparel", "identifier": "Apparel", "description": "The latest styles for the entire family.", "thumbnail": "images/catalog/apparel/women/category/catr_wcl_pants.png", "seo": { "href": "/shop/apparel" }, "children": [ { "id": "2", "name": "Men", "identifier": "Men", "description": "Men", "thumbnail": "images/catalog/apparel/men/category/catr_app_men.png", "seo": { "href": "/shop/apparel/men" }, "children": [ { "href": "/api/v2/categories?storeId=1&id=10013" }, { "href": "/api/v2/categories?storeId=1&id=10012" }, { "href": "/api/v2/categories?storeId=1&id=10011" }, { "href": "/api/v2/categories?storeId=1&id=10010" }, { "href": "/api/v2/categories?storeId=1&id=10014" } ] }, { "id": "5", "name": "Girls", "identifier": "Girls", "description": "Girls", "thumbnail": "images/catalog/apparel/girls/category/catr_app_girls.png", "seo": { "url": "/shop/apparel/girls" }, "children": [ { "href": "/api/v2/categories?storeId=1&id=10015" }, { "href": "/api/v2/categories?storeId=1&id=10016" }, { "href": "/api/v2/categories?storeId=1&id=10017" }, { "href": "/api/v2/categories?storeId=1&id=10018" } ] }, { "id": "4", "name": "Boys", "identifier": "Boys", "description": "Boys", "thumbnail": "images/catalog/apparel/boys/category/catr_app_boys.png", "seo": { "url": "/shop/apparel/boys" }, "children": [ { "href": "/api/v2/categories?storeId=1&id=10019" }, { "href": "/api/v2/categories?storeId=1&id=10020" }, { "href": "/api/v2/categories?storeId=1&id=10021" } ] }, { "id": 3, "name": "Women", "identifier": "Women", "description": "Women", "thumbnail": "images/catalog/apparel/women/category/catr_app_women.png", "seo": { "url": "/shop/apparel/women" }, "children": [ { "href": "/api/v2/categories?storeId=1&id=10003" }, { "href": "/api/v2/categories?storeId=1&id=10007" }, { "href": "/api/v2/categories?storeId=1&id=10008" }, { "href": "/api/v2/categories?storeId=1&id=10002" }, { "href": "/api/v2/categories?storeId=1&id=10006" }, { "href": "/api/v2/categories?storeId=1&id=10001" }, { "href": "/api/v2/categories?storeId=1&id=10004" }, { "href": "/api/v2/categories?storeId=1&id=10005" } ] } ] }, { ... rest of top categories ... } ] }
content-type: application/json;charset=UTF-8 date: Sun, 02 Feb 2020 22:15:28 GMT transfer-encoding: chunked
- Products example 1
- Request
URL:
Request header:GET /api/v2/products?storeId=1&id=10046&associationType=accessories or GET /api/v2/products?storeId=1&id=10046&id=10045&associationType=accessories v1 equivalent /search/resources/store/{id}/productview/byId/{productId} /search/resources/store/{id}/productview/byIds
Response body:accept: application/json
{ "contents": [ { "id": "11907", "description": "Relaxed fit traditional cut two button suit", "type": "product", "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg", "buyable": true, "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg", "sku": "MCL008_0819", "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit", "manufacturer": "Hermitage Collection", "seo": { "href": "/...." }, "links": { "self": { "href": "/api/v2/products?storeId=1&id=11907" }, "parent": { "href": "/api/v2/categories?storeId=1&id=10001" } }, "price": [ { "usage": "Display", "currency": "USD", "value": 980 }, { "usage": "Offer", "currency": "USD", "value": 980 } ], "items": [ { "id": "11908", "description": "Relaxed fit traditional cut two button suit", "type": "item", "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg", "buyable": true, "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg", "sku": "MCL008_081901", "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit", "manufacturer": "Hermitage Collection", "price": [ { "usage": "Display", "currency": "USD", "value": 980 }, { "usage": "Offer", "currency": "USD", "value": 980 } ], "links": { "self": { "href": "/api/v2/products?storeId=1&id=11988" }, "parent": { "href": "/api/v2/categories?storeId=1&id=10001" } }, "attributes": [ { "identifier": "MenSuitsColor", "usage": "Defining", "values": [ { "identifier": "Black", "unit": { "name": "one", "id": "C62" }, "value": "Black", "id": "7000000000000000904" } ], "name": "Color", "id": "7000000000000000047" }, { "identifier": "MenSuitsSize", "usage": "Defining", "values": [ { "identifier": "40R", "unit": { "name": "one", "id": "C62" }, "value": "40R", "id": "7000000000000000908" } ], "name": "Size", "id": "7000000000000000048" } ] }, { ... rest of items ... } ], "attributes": [ { "identifier": "MenSuitsColor", "usage": "Defining", "values": [ { "identifier": "Black", "unit": { "name": "one", "id": "C62" }, "value": "Black", "id": "7000000000000000904" } ], "name": "Color", "comparable": true, "id": "7000000000000000047" }, { "identifier": "MenSuitsSize", "usage": "Defining", "values": [ { "identifier": "44L", "unit": { "name": "one", "id": "C62" }, "value": "44L", "id": "7000000000000000912" }, { "identifier": "44R", "unit": { "name": "one", "id": "C62" }, "value": "44R", "id": "7000000000000000911" }, { ... rest of attribute values ... } ], "name": "Size", "comparable": true, "id": "7000000000000000048" } ], "associations": [ { "id": "11907", "description": "Relaxed fit traditional cut two button suit", "type": "product", "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg", "buyable": true, "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg", "sku": "MCL008_0819", "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit", "manufacturer": "Hermitage Collection", "seo": { "href": "/...." }, "links": { "self": { "href": "/api/v2/products?storeId=1&id=11907" }, "parent": { "href": "/api/v2/categories?storeId=1&id=10001" } }, "price": [ { "usage": "Display", "currency": "USD", "value": 980 }, { "usage": "Offer", "currency": "USD", "value": 980 } ], } ] }, { "id": "11908", "description": "Relaxed fit traditional cut two button suit", "type": "item", "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg", "buyable": true, "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg", "sku": "MCL008_081901", "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit", "manufacturer": "Hermitage Collection", "seo": { "href": "/...." }, "links": { "self": { "href": "/api/v2/products?storeId=1&id=11908" }, "parent": { "href": "/api/v2/categories?storeId=1&id=10001" } }, "price": [ { "usage": "Display", "currency": "USD", "value": 980 }, { "usage": "Offer", "currency": "USD", "value": 980 } ], "attributes": [ { "identifier": "MenSuitsColor", "usage": "Defining", "values": [ { "identifier": "Black", "unit": { "name": "one", "id": "C62" }, "value": "Black", "id": "7000000000000000904" } ], "name": "Color", "comparable": true, "id": "7000000000000000047" }, { "identifier": "MenSuitsSize", "usage": "Defining", "values": [ { "identifier": "40R", "unit": { "name": "one", "id": "C62" }, "value": "40R", "id": "7000000000000000908" } ], "name": "Size", "comparable": true, "id": "7000000000000000048" } ] } ] }
- Products example 2
- Request
URL:
Request header:/api/v2/products?storeId=1&categoryId=10001 v1 equivalent /search/resources/store/{id}/productview/byCategory/{categoryId}
Response body:accept: application/json
Response header:{ "total": 56, "offset": 12, "limit": 12, "next": "/api/v2/products?storeId=1&categoryId=10001&id=11909&limit=12&offset=24", "previous": "/api/v2/products?storeId=1&categoryId=10001&id=11909&limit=12&offset=0", "contents": [ { "id": "11907", "description": "Relaxed fit traditional cut two button suit", "type": "product", "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg", "buyable": true, "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg", "sku": "MCL008_0819", "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit", "manufacturer": "Hermitage Collection", "seo": { "href": "/...." }, "links": { "self": { "href": "/api/v2/products?storeId=1&id=11907" }, "parent": { "href": "/api/v2/categories?storeId=1&id=10001" } }, "price": [ { "usage": "Display", "currency": "USD", "value": 980 }, { "usage": "Offer", "currency": "USD", "value": 980 } ], "items": [ { "href": "/api/v2/products?storeId=1&id=11988" }, { "href": "/api/v2/products?storeId=1&id=11909" } ] }, ..... other products in the search result set .... { "id": "11907", "description": "Relaxed fit traditional cut two button suit", "type": "product", "parent": "/api/v2/categories/10001?storeId=1", "image": "images/catalog/apparel/men/mcl008_suits/646x1000/mcl008_0819.jpg", "buyable": true, "thumbnail": "images/catalog/apparel/men/mcl008_suits/200x310/mcl008_0819.jpg", "sku": "MCL008_0819", "name": "Hermitage Black Relaxed Fit Traditional Two Button Suit", "manufacturer": "Hermitage Collection", "seo": { "href": "/...." }, "links": { "self": { "href": "/api/v2/products?storeId=1&id=11908" }, "parent": { "href": "/api/v2/categories?storeId=1&id=10001" } }, "price": [ { "usage": "Display", "currency": "USD", "value": 980 }, { "usage": "Offer", "currency": "USD", "value": 980 } ], "items": [ { "href": "/api/v2/products?storeId=1&id=11988" }, { "href": "/api/v2/products?storeId=1&id=11909" } ] } ], "facets": [ { "value": "price_USD", "name": "price_USD", "entry": [ { "count": 0, "label": "*-100.0", "value": "price_USD%3A*-100.0" }, { "count": 0, "label": "100.0-200.0", "value": "price_USD%3A100.0-200.0" }, { ... rest of facet entries ... } ] } ] }
content-type: application/json;charset=UTF-8 date: Sun, 02 Feb 2020 22:15:28 GMT transfer-encoding: chunked
- SEO URL example 1: request by identifier for a category
- Request
URL:
Request header:GET /api/v2/urls?storeId=12101&identifier=Bath or GET /api/v2/urls?storeId=12101&identifier=Bath,Accessories
Response body:accept: application/json
{ "contents": [ { "id": 18801, "identifier": "bath", "status": 1, "tokenName": "CategoryToken", "tokenValue": "11509", "tokenExternalValue": "Bath", "storeId": 12101, "redirectURL": "", "page": { "name": "CATEGORY_PAGE", "type": "CATEGORY_PAGE", "layout": "", "title": "Bath | Stockholm", "metaKeyword": "space, light, faucet, mirror, brush, bath, decor", "metaDescription": "Modernize your bath space with a variety of vanity fixtures and lighting options", "imageAlternateDescription": "Image for Bath from Stockholm" } }, { "id": 18804, "identifier": "accessories", "status": 1, "tokenName": "CategoryToken", "tokenValue": "11509", "tokenExternalValue": "Accessories", "storeId": 12101, "redirectURL": "", "page": { "name": "CATEGORY_PAGE", "type": "PRODUCT_LISTING_PAGE", "layout": "", "title": "Accessories | Stockholm", "metaKeyword": "makeup mirrors, style, space, bath", "metaDescription": "Accent your bath with stylish accessories and makeup mirrors", "imageAlternateDescription": "Image for Accessories from Stockholm" } ] }
- SEO URL example 2: request by identifier for a product
- Request
URL:
Request header:GET /api/v2/urls?storeId=12101&identifier=makeup-mirror-br-acce-0001 or GET /api/v2/urls?storeId=12101
Response body:accept: application/json
Response header:{ "contents": [ { "id": 18501, "identifier": "makeup-mirror-br-acce-0001", "status": 1, "tokenName": "ProductToken", "tokenValue": "15733", "tokenExternalValue": "BR-ACCE-0001", "storeId": 12101, "redirectURL": "", "page": { "name": "PRODUCT_PAGE", "type": "PRODUCT_PAGE", "layout": "", "title": "Makeup Mirror | Stockholm", "metaKeyword": "Stockholm", "metaDescription": "A modern makeup mirror that sits elegantly on any bathroom counter.", "imageAlternateDescription": "Image for Makeup Mirror from Stockholm" } } ] }
content-type: application/json;charset=UTF-8 date: Sun, 02 Feb 2020 22:15:28 GMT transfer-encoding: chunked