OCAPI Expansions

To minimize network traffic and server CPU usage, the Open Commerce API sometimes uses a technique called expansion. This technique intentionally omits parts of a selected resource, reducing the size of the overall response. However, if you want to include the parts that are omitted by default, you can explicitly request the omitted parts by using the expand query parameter. This parameter specifies a comma-separated list of entities that you want expanded, identifying each of them by name.

The products and product_search resources support the expansion technique. A resource type that enables expansions is structured into a base resource and one or more subresources. For the *products* resource, the base resource is */products/{id}*, and two of its subresources are */products/{id}/prices* and */products/{id}/variations*.

By default, the base resource returns only a basic subset of properties. A subresource returns not only the base properties but also subresource specific properties (for example, price properties). The name of the subresource is used as the expand query parameter value.

The examples below show how expansion works.

Request to base resource without expand parameter specified. Response document contains only some basic properties.

1REQUEST:
2GET /dw/shop/v24_5/products/123 HTTP/1.1
3
4RESPONSE:
5HTTP/1.1 200 OK
6Content-Length: 67
7Content-Type: application/json; charset=UTF-8
8Cache-Control: max-age=60,must-revalidate
9
10{
11  "id":"123",
12  "name":"Ultimate T-Shirt XXXL"
13}

Two requests to separate subresources. A subresource response document contains the basic properties plus subresource specific properties.

1REQUEST 1:
2GET /dw/shop/v24_5/products/123/availability HTTP/1.1
3
4RESPONSE 1:
5HTTP/1.1 200 OK
6Content-Length: 67
7Content-Type: application/json; charset=UTF-8
8Cache-Control: max-age=60,must-revalidate
9
10{
11  "id":"123",
12  "name":"Ultimate T-Shirt XXXL",
13  "orderable":true
14}

1REQUEST 2:
2GET /dw/shop/v24_5/products/123/prices HTTP/1.1
3
4RESPONSE 2:
5HTTP/1.1 200 OK
6Content-Length: 67
7Content-Type: application/json; charset=UTF-8
8Cache-Control: max-age=60,must-revalidate
9
10{
11  "id":"123",
12  "name":"Ultimate T-Shirt XXXL",
13  "price":14.65
14}

Single request with expand parameter. The response document contains the basic properties plus the specific properties of each subresource named in expand parameter values.

1REQUEST:
2GET /dw/shop/v24_5/products/123?expand=availability,prices HTTP/1.1
3
4RESPONSE:
5HTTP/1.1 200 OK
6Content-Length: 67
7Content-Type: application/json; charset=UTF-8
8Cache-Control: max-age=60,must-revalidate
9
10{
11  "id":"123",
12  "name":"Ultimate T-Shirt XXXL",
13  "orderable":true,
14  "price":14.65
15}