OCAPI HTTP versions 23.2

OCAPI expects requests and returns responses by default with HTTP version 1.1. However, it is possible to use HTTP version 2 if the instance belongs to the Primary Instance Group (Production, Staging, and Development) or is an On-Demand Sandbox (ODS). This page describes the difference in HTTP header formats regarding the versions.

HTTP/1.1

In HTTP/1.1, header names are case-insensitive, as per RFC 2616, Hypertext Transfer Protocol — HTTP/1.1, Section 4.2:

Each header field consists of a name followed by a colon (":") and the field value. Field names are case-insensitive.  

This means that a specific format must not be assumed by the server or client. Therefore, the response may contain header names in a mixed-case format:

Accept-Ranges: bytes
x-dw-request-base-id: RgFS4PN7HWQCABqs
Allow: GET,HEAD,OPTIONS
X-Content-Type-Options: nosniff
x-dw-version-status: deprecated
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
jweb: y
Content-Type: application/json;charset=UTF-8
Content-Length: 864 

HTTP/2

In HTTP/2, header names must be lowercase, as per RFC 7540, Hypertext Transfer Protocol Version 2 (HTTP/2), Section 8.1.2:

Just as in HTTP/1.x, header field names are strings of ASCII characters that are compared in a case-insensitive fashion.
However, header field names MUST be converted to lowercase prior to their encoding in HTTP/2. A request or response
containing uppercase header field names MUST be treated as malformed (Section 8.1.2.6).   

This means that uppercase header names in the request must not be accepted and the response will always have lowercase names:

accept-ranges: bytes
x-dw-request-base-id: RgFS4PN7HWQCABqs
allow: GET,HEAD,OPTIONS
x-content-type-options: nosniff
x-dw-version-status: deprecated
cache-control: max-age=0,no-cache,no-store,must-revalidate
jweb: y
content-type: application/json;charset=UTF-8
content-length: 864  

Additional note

Usually, HTTP clients capable of HTTP/2 will automatically do the format conversion. But it should be noted that header names have been case-insensitive since the publishing of HTTP/1.1 in 1999. As a consequence, code that behaves as case-sensitive (i.e. it assumes a specific case) should be fixed in order to avoid issues with future HTTP standards.

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.