Categories Resource (Shop API 17.3)
Summary
| Http Method | Resource | Description |
|---|---|---|
| GET | /Categories/({Id},...,{Id}) | When you use the URL template below, the server returns multiple categories (a result object of category documents). You can use this template as a convenient way of obtaining multiple categories in a single request, instead of issuing separate requests for each category. You can specify multiple ids (up to a maximum of 50). You must enclose the list of ids in parentheses. If a category identifier contains a parenthesis or the separator sign, you must URL encode the character. The server only returns online categories. |
| GET | /Categories/{Id} | When you use the URL template below, the server returns a category identified by its id; by default, the server also returns the first level of subcategories, but you can specify another level by setting the levels parameter. The server only returns online categories. |
Get Multiple Categories
When you use the URL template below, the server returns multiple categories (a result object of category documents). You can use this template as a convenient way of obtaining multiple categories in a single request, instead of issuing separate requests for each category. You can specify multiple ids (up to a maximum of 50). You must enclose the list of ids in parentheses. If a category identifier contains a parenthesis or the separator sign, you must URL encode the character. The server only returns online categories.Url
GET http://hostname:port/dw/shop/v17_3/categories/({id},...,{id})?levels={Integer}&locale={String}Formats
json, xml
Authentication
| Name | Description |
|---|---|
| JWT | Authentication via Customer JWT token. |
| None | No authentication. |
Response Document
Path Parameters
| Parameter | Type | Description | Constraints |
|---|---|---|---|
| ids | [String] | The comma separated list of category ids. | maxItems=50, maxLength=256 |
Query Parameters
| Parameter | Type | Description | Constraints |
|---|---|---|---|
| levels | Integer | Specifies how many levels of nested subcategories you want the server to return. The default value is 1. Valid values are 0, 1, or 2. | maxIntegerValue=2, minIntegerValue=0 |
| locale | String | The locale context. |
Customization
This Resource supports server-side customization.
| Extension Point | Method Detail |
|---|---|
dw.ocapi.shop.category.afterGET
|
afterGET (doc : Document) : Status The function is called after the request has been processed.
|
Sample
REQUEST:
GET /dw/shop/v17_3/categories/(mens,womens)?levels=0 HTTP/1.1
Host: example.com
Accept: application/json
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
"_v":"17.3",
"_type":"category_result",
"count":2,
"total":2,
"data":
[{
"id":"mens",
"name":"Mens",
"description":"",
"image":"http://foo.com.bar.jpg",
"thumbnail":"http://foo.com.bar.jpg",
"parent_category_id":"root"
},{
"id":"womens",
"name":"Womens",
"description":"",
"image":"http://foo.com.bar.jpg",
"thumbnail":"http://foo.com.bar.jpg",
"parent_category_id":"root"
}]
}Get Category
When you use the URL template below, the server returns a category identified by its id; by default, the server also returns the first level of subcategories, but you can specify another level by setting the levels parameter. The server only returns online categories.Url
GET http://hostname:port/dw/shop/v17_3/categories/{id}?levels={Integer}&locale={String}Formats
json, xml
Authentication
| Name | Description |
|---|---|
| JWT | Authentication via Customer JWT token. |
| None | No authentication. |
Response Document
Path Parameters
| Parameter | Type | Description | Constraints |
|---|---|---|---|
| id | String | The id of the requested category. | maxLength=256 |
Query Parameters
| Parameter | Type | Description | Constraints |
|---|---|---|---|
| levels | Integer | Specifies how many levels of nested subcategories you want the server to return. The default value is 1. Valid values are 0, 1, or 2. | maxIntegerValue=2, minIntegerValue=0 |
| locale | String | The locale context. |
In case of a failure Fault Document is returned.
Faults
| Status | Type | Arguments | Description |
|---|---|---|---|
| 404 |
CategoryNotFoundException
|
categoryId (String) siteId (String) |
Thrown if the server could not find an online category with the specified id. |
Customization
This Resource supports server-side customization.
| Extension Point | Method Detail |
|---|---|
dw.ocapi.shop.category.modifyGETResponse
|
modifyGETResponse (scriptCategory : Category , doc : Category ) : Status The function is called after the request has been processed.
|
Sample
REQUEST:
GET /dw/shop/v17_3/categories/root?levels=2 HTTP/1.1
Host: example.com
Accept: application/json
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
"_v":"17.3",
"_type":"category",
"id":"root",
"categories":[
{
"id":"mens",
"name":"Mens",
"description":"",
"image":"http://foo.com.bar.jpg",
"thumbnail":"http://foo.com.bar.jpg",
"parent_category_id":"root",
"categories":[{
"id":"footwear",
"name":"Footwear",
"description":"",
"image":"http://foo.com.bar.jpg",
"thumbnail":"http://foo.com.bar.jpg",
"parent_category_id":"mens"
},{
"id":"clothing",
"name":"Clothing",
"description":"",
"image":"http://foo.com.bar.jpg",
"thumbnail":"http://foo.com.bar.jpg",
"parent_category_id":"mens"
}]
},
{
"id":"womens",
"name":"Womens",
"description":"",
"image":"http://foo.com.bar.jpg",
"thumbnail":"http://foo.com.bar.jpg",
"parent_category_id":"root",
"categories":[{
"id":"footwear",
"name":"Footwear",
"description":"",
"image":"http://foo.com.bar.jpg",
"thumbnail":"http://foo.com.bar.jpg",
"parent_category_id":"womens"
},{
"id":"clothing",
"name":"Clothing",
"description":"",
"image":"http://foo.com.bar.jpg",
"thumbnail":"http://foo.com.bar.jpg",
"parent_category_id":"womens"
}]
}]
}X
OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.