Categories resource (Shop API 19.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/v19_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

CategoryResult

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. minIntegerValue=0
locale String The locale context.  

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.category.beforeGET

beforeGET (categoryId : String ) : Status

The function is called before the request will be processed.

Parameters:
categoryId - the id of the category
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.category.modifyGETResponse

modifyGETResponse (scriptCategory : Category , doc : Category ) : Status

The function is called after the request has been processed.

Parameters:
scriptCategory - an instance of dw.catalog.Category
doc - the document
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_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":"19.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/v19_3/categories/{id}?levels={Integer}&locale={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
None No authentication.

Response Document

Category

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. 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.beforeGET

beforeGET (categoryId : String ) : Status

The function is called before the request will be processed.

Parameters:
categoryId - the id of the category
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.category.modifyGETResponse

modifyGETResponse (scriptCategory : Category , doc : Category ) : Status

The function is called after the request has been processed.

Parameters:
scriptCategory - an instance of dw.catalog.Category
doc - the document
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v19_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":"19.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"
    }]
  }]
}