OCAPI expansions 23.2

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.

Base resource

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

REQUEST:
GET /dw/shop/v23_2/products/123 HTTP/1.1
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate
 
{
  "id":"123",
  "name":"Ultimate T-Shirt XXXL"
}

Sub resource

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

REQUEST 1:
GET /dw/shop/v23_2/products/123/availability HTTP/1.1
 
RESPONSE 1:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate
 
{
  "id":"123",
  "name":"Ultimate T-Shirt XXXL",
  "orderable":true
}
REQUEST 2:
GET /dw/shop/v23_2/products/123/prices HTTP/1.1
 
RESPONSE 2:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate
 
{
  "id":"123",
  "name":"Ultimate T-Shirt XXXL",
  "price":14.65
}

Base resource with expand

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

REQUEST:
GET /dw/shop/v23_2/products/123?expand=availability,prices HTTP/1.1
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate
 
{
  "id":"123",
  "name":"Ultimate T-Shirt XXXL",
  "orderable":true,
  "price":14.65
}
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.