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
}