OCAPI batch requests 23.2

Overview

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.

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:

Content-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.

CORS Support

Formatting of Multipart sub requests

Sub requests in a batch request body adhering to the standard defined in Multipart Media Type. This means that the header section in a Multipart sub request 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 sub request.

    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
    x-dw-http-method: DELETE
    x-dw-resource-path: /s/-/dw/data/v23_2/libraries/SiteGenesis/content/
    --23dh3f9f4\n
    x-dw-content-id: realCount\n
    \n
    {"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
    --23dh3f9f4--
    ...

Example 2

Wrong formatted sub request. Only one newline after header section.

    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
    x-dw-http-method: DELETE
    x-dw-resource-path: /s/-/dw/data/v23_2/libraries/SiteGenesis/content/
    -23dh3f9f4\n
    x-dw-content-id: realCount\n
    {"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
    --23dh3f9f4--
    ...

Example 3

Wrong formatted sub request. Two newlines after boundary will lead to an empty header section.

    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
    x-dw-http-method: DELETE
    x-dw-resource-path: /s/-/dw/data/v23_2/libraries/SiteGenesis/content/
    --23dh3f9f4\n
    \n
    x-dw-content-id: realCount\n
    {"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
    --23dh3f9f4--
    ...
    

Example batch requests

Example 1

    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
    x-dw-http-method: DELETE
    x-dw-resource-path: /s/-/dw/data/v23_2/libraries/SiteGenesis/content/

    --23dh3f9f4
    x-dw-content-id: req1
    x-dw-resource-path-extension: content_asset_1
    --23dh3f9f4
    ...
    x-dw-content-id: req50
    x-dw-resource-path-extension: content_asset_50
    --23dh3f9f4--

    RESPONSE:
    HTTP/1.1 200 OK
    Content-Type: multipart/mixed; boundary=23dh3f9f4

    --23dh3f9f4
    x-dw-content-id: req1
    x-dw-status-code: 204
    --23dh3f9f4
    ...
    x-dw-content-id: req50
    x-dw-status-code: 204
    --23dh3f9f4--
    

Example 2

    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    x-dw-client-id: [your_own_client_id]
    x-dw-http-method: GET
    x-dw-resource-path: /s/SiteGenesis/dw/shop/v23_2/

    --23dh3f9f4
    x-dw-content-id: req_addr_create
    x-dw-http-method: PUT
    x-dw-resource-path-extension: account/this/addresses

    {
      "address1":"10 Somewhere St.",
      "city":"Boston",
      "last_name":"Lebowski",
      "country_code":"US",
      "postal_code":"98765",
      "state_code":"MA"
    }
    --23dh3f9f4
    x-dw-content-id: req_prod_get
    x-dw-resource-path-extension: products/creative-zen-v
    --23dh3f9f4--

    RESPONSE:
    HTTP/1.1 200 OK
    Content-Type: multipart/mixed; boundary=23dh3f9f4

    --23dh3f9f4
    x-dw-content-id: req_addr_create
    x-dw-status-code: 200

    {
      "_v" : "23.2",
      "_type":"customer_address",
      "address1":"10 Somewhere St.",
      "address_id":"84619.10625703718",
      "city":"Boston",
      "country_code":"US",
      "last_name":"Lebowski",
      "postal_code":"98765",
      "state_code":"MA"
    }
    --23dh3f9f4
    x-dw-content-id: req_prod_get
    x-dw-status-code: 404

    {
      "_v" : "23.2",
      "fault":{
        "type":"ProductNotFoundException",
        "message":"No product with id 'creative-zen-v' for site 'SiteGenesis' found."
      }
    }
    --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