Categories Resource (Shop API 16.2)

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/v16_2/categories/({id},...,{id})?levels={Integer}&locale={String}

Formats

json, xml

Authentication

Name Description
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. 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.

Parameters:
doc - the document
Returns:
  • Status.OK for success.
  • Status.ERROR in case something went wrong.

Sample

REQUEST:
GET /dw/shop/v16_2/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":"16.2",
  "_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/v16_2/categories/{id}?levels={Integer}&locale={String}

Formats

json, xml

Authentication

Name Description
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. 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.afterGET

afterGET (doc : Document) : Status

The function is called after the request has been processed.

Parameters:
doc - the document
Returns:
  • Status.OK for success.
  • Status.ERROR in case something went wrong.

Sample

REQUEST:
GET base_url/v16_2/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":"16.2",
  "_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"
    }]
  }]
}