OCAPI Batch Requests

An OCAPI batch request is a multipart HTTP request that can contain up to 50 subrequests. Each subrequest (part) must operate on a single resource; subrequests that specify multiple ids (for example, '/products/(p1,p2...)') are forbidden.

Batch requests reduce network overhead by reducing the overall amount of information transmitted and by reducing the number of calls you have to make. For example, to build an application screen, you can construct a single large multipart batch request instead of constructing numerous smaller individual OCAPI requests.

The HTTP method used for the batch request as a whole must be POST or OPTIONS. Each subrequest can specify a different HTTP method if necessary.

Batch Request Format

Each batch request has a main header section. In this section, you must include a Content-Type header that specifies a type (multipart/mixed) and a boundary separator that is used to delimit each subrequest. For example:

1Content-Type: multipart/mixed; boundary=23dh3f9f4

Every header included in the main header section of the batch request is implicitly inherited by each subrequest. The query parameters of the main batch request are also implicitly inherited by each subrequest.

Each subrequest, however, is conceptually a complete OCAPI request with its own resource path, header section, and request body. If needed, a subrequest can override its inherited headers and its inherited query parameters.

To specify the behavior of subrequests and to define the mapping between requests and responses, you must specify the following headers where appropriate:

Header name	Location	Description
`x-dw-http-method`	request, subrequest	Specifies the HTTP method used to access the resource.
`x-dw-resource-path`	request, subrequest	Specifies the base resource path. The value of this header is combined with value of the `x-dw-resource-path-extension` header to provide a complete resource path.
`x-dw-resource-path-extension`	request, subrequest	Specifies an extension for the value of the base path, as specified by the `x-dw-resource-path` header. This header is optional if the base resource path already represents a valid OCAPI resource.
`x-dw-content-id`	subrequest, subresponse	Specifies an ID of the subrequest. This header value is used to map a subrequest to a subresponse.
`x-dw-status-code`	subresponse	Specifies the status code of a single subresponse.

CORS Support

Batch requests are supporting CORS. Allowed expose headers and origins are mentioned in OCAPI settings for each client ID. To access them, it’s mandatory to send a batch request for a specific client in a context, either of a specific site or global. There are several possibilities to pass a client identification:

Client ID as query parameter
Client ID as x-dw-client-id header
OAuth access token via Authorization header
JWT via Authorization header

Formatting of Multipart Sub Requests

Subrequests in a batch request body adhering to the standard defined in Multipart Media Type. This approach means that the header section in a Multipart subrequest has to follow directly after the Multipart boundary. The header section and the Multipart body section have to be separated by two subsequent newline characters.

Example 1

Correct formatted subrequest.

1REQUEST:
2    POST /batch HTTP 1.1
3    Host: example.com
4    Content-Type: multipart/mixed; boundary=23dh3f9f4
5    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
6    x-dw-http-method: DELETE
7    x-dw-resource-path: /s/-/dw/data/v24_5/libraries/SiteGenesis/content/
8    --23dh3f9f4\n
9    x-dw-content-id: realCount\n
10    \n
11    {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
12    --23dh3f9f4--
13    ...

Example 2

Wrong formatted subrequest. Only one newline after header section.

1REQUEST:
2    POST /batch HTTP 1.1
3    Host: example.com
4    Content-Type: multipart/mixed; boundary=23dh3f9f4
5    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
6    x-dw-http-method: DELETE
7    x-dw-resource-path: /s/-/dw/data/v24_5/libraries/SiteGenesis/content/
8    -23dh3f9f4\n
9    x-dw-content-id: realCount\n
10    {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
11    --23dh3f9f4--
12    ...

Example 3

Wrong formatted subrequest. Two newlines after boundary lead to an empty header section.

1REQUEST:
2    POST /batch HTTP 1.1
3    Host: example.com
4    Content-Type: multipart/mixed; boundary=23dh3f9f4
5    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
6    x-dw-http-method: DELETE
7    x-dw-resource-path: /s/-/dw/data/v24_5/libraries/SiteGenesis/content/
8    --23dh3f9f4\n
9    \n
10    x-dw-content-id: realCount\n
11    {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
12    --23dh3f9f4--
13    ...

Example Batch Requests

Example 1

This example shows how you can access multiple resources of the same type:

1REQUEST:
2    POST /batch HTTP 1.1
3    Host: example.com
4    Content-Type: multipart/mixed; boundary=23dh3f9f4
5    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
6    x-dw-http-method: DELETE
7    x-dw-resource-path: /s/-/dw/data/v24_5/libraries/SiteGenesis/content/
8
9    --23dh3f9f4
10    x-dw-content-id: req1
11    x-dw-resource-path-extension: content_asset_1
12    --23dh3f9f4
13    ...
14    x-dw-content-id: req50
15    x-dw-resource-path-extension: content_asset_50
16    --23dh3f9f4--
17
18    RESPONSE:
19    HTTP/1.1 200 OK
20    Content-Type: multipart/mixed; boundary=23dh3f9f4
21
22    --23dh3f9f4
23    x-dw-content-id: req1
24    x-dw-status-code: 204
25    --23dh3f9f4
26    ...
27    x-dw-content-id: req50
28    x-dw-status-code: 204
29    --23dh3f9f4--

Example 2

This example shows how you can access resources of different types:

1REQUEST:
2    POST /batch HTTP 1.1
3    Host: example.com
4    Content-Type: multipart/mixed; boundary=23dh3f9f4
5    x-dw-client-id: [your_own_client_id]
6    x-dw-http-method: GET
7    x-dw-resource-path: /s/SiteGenesis/dw/shop/v24_5/
8
9    --23dh3f9f4
10    x-dw-content-id: req_addr_create
11    x-dw-http-method: PUT
12    x-dw-resource-path-extension: account/this/addresses
13
14    {
15      "address1":"10 Somewhere St.",
16      "city":"Boston",
17      "last_name":"Lebowski",
18      "country_code":"US",
19      "postal_code":"98765",
20      "state_code":"MA"
21    }
22    --23dh3f9f4
23    x-dw-content-id: req_prod_get
24    x-dw-resource-path-extension: products/creative-zen-v
25    --23dh3f9f4--
26
27    RESPONSE:
28    HTTP/1.1 200 OK
29    Content-Type: multipart/mixed; boundary=23dh3f9f4
30
31    --23dh3f9f4
32    x-dw-content-id: req_addr_create
33    x-dw-status-code: 200
34
35    {
36      "_v" : "24.5",
37      "_type":"customer_address",
38      "address1":"10 Somewhere St.",
39      "address_id":"84619.10625703718",
40      "city":"Boston",
41      "country_code":"US",
42      "last_name":"Lebowski",
43      "postal_code":"98765",
44      "state_code":"MA"
45    }
46    --23dh3f9f4
47    x-dw-content-id: req_prod_get
48    x-dw-status-code: 404
49
50    {
51      "_v" : "24.5",
52      "fault":{
53        "type":"ProductNotFoundException",
54        "message":"No product with id 'creative-zen-v' for site 'SiteGenesis' found."
55      }
56    }
57    --23dh3f9f4--

Request Site Context

The site context for each request can be defined in x-dw-resource-path or x-dw-resource-path-extension. If no site context is given in these headers, the one from the main request is taken. This implies, that the site context from the main request can be overwritten by the resource path headers.

Limitations

The size of the batch request body is limited to 5 MB. The maximum number of subrequests is 50.

Exceptions

Exeption name	Status code	Description
`IllegalContentTypeException`	400	Thrown if the request content type isn’t multipart/mixed or specifies no boundary.
`IllegalQueryStringException`	400	Thrown if the query string for the request or a subrequest is invalid.
`InvalidAuthorizationHeaderException`	401	Thrown if the authorizarion header has not the format Authorization: Bearer …
`InvalidHttpMethodException`	400	Thrown if the HTTP method in the request header or subrequest header is invalid.
`InvalidRequestBodyException`	400	Thrown if the request body is invalid.
`InvalidTokenException`	401	The token sent via Authorization: Bearer header is invalid or expired.
`MethodNotAllowedException`	405	Thrown if the batch request was sent with an HTTP method other than POST or OPTIONS.
`MissingClientIdException`	400	Thrown if no client identification was sent with the main request (either as client ID or authorization token).
`MissingHttpMethodException`	400	Thrown if at least one subrequest has no HTTP method.
`MissingResourcePathException`	400	Thrown if at least one subrequest has no resource path.
`QuotaExceededException`	400	Thrown if the batch request contains more than 50 subrequests.
`RequestEntityTooLargeException`	400	Thrown if the batch request body is larger than 5 MB.
`ResourcePathNotAllowedException`	400	Thrown if at least one subrequest is a multiple-ID resource call.
`UnauthorizedOriginException`	401	Thrown if the given origin isn’t mentioned in the OCAPI settings for the accessing client.
`UnknownClientIdException`	401	Thrown if the given client identification isn’t known to the account manager.
`UnknownSiteIdException`	400	Thrown if the request was sent in the context of an unknown site name.

Attention!

The Open Commerce API (OCAPI) is now deprecated. The provisions described in our versioning and deprecation policy fully apply. For all new projects and major refactoring work, use B2C Commerce API (SCAPI) as the default REST API. For additional details, refer to Why Use SCAPI Instead of OCAPI.

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!