CORS support

Only a small subset of APIs can be called from a client web browser. See CDS CORS.

These unauthenticated endpoints require CORS (Cross-Origin Resource Sharing) support.

CORS allows a script on a web page on one domain to make a request for data hosted on another domain. Unless CORS is implemented, a cross-origin request, across different domains, is disallowed by the browser’s same origin policy. 

Implementing CORS on unauthenticated endpoints allows resources such as product data to be widely available, including to web browser-based applications such as product comparison sites.

For an endpoint to indicate that it allows CORS requests, it should respond to requests made by browsers as described below.

• In addition to the GET method, support the OPTIONS method for the URI of each respective endpoint, to support a CORS preflight request. A preflight request provides headers on the OPTIONS request indicating which headers will be used in the actual request. For example:
  • Access-Control-Request-Method: GET
  • Access-Control-Request-Headers: x-min-v, x-v, Cache-Control, x-fapi-interaction-id
• The OPTIONS response must include the following headers at a minimum:
  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Methods: GET
    All unauthenticated endpoints currently use the GET method.
  • Access-Control-Allow-Headers: x-min-v, x-v, Cache-Control, x-fapi-interaction-id
  • The OPTIONS response may include the Access-Control-Max-Age header to allow the details from the preflight response to be cached by the browser for a defined period. The example below allows caching for one day:
  • Access-Control-Max-Age: 86400
• If the OPTIONS request is successful, a subsequent request for the data will be made by the browser using the GET method, including any optional or mandatory headers such as x-min-v, x-v and x-fapi-interaction-id.
• The response to the GET request must include the following headers at a minimum
  • x-v: the version of payload schema being returned
  • Access-Control-Allow-Origin: *
  • Access-Control-Expose-Headers: x-v, Retry-After, x-fapi-interaction-id
• The GET response may also include:
  • x-fapi-interaction-id: the UUID generated or played-back from the request, where supported by the Data Holder

Convention CDS-DC-005 provides a recommendation on handling the x-v header field in CORS implementations. 

See:

• CDS CORS
• CDS HTTP Headers

See also Mozilla developer documentation on CORS: 

• Cross-Origin Resource Sharing (CORS)

CORS OPTIONS preflight request headers

• Access-Control-Request-Method
• Access-Control-Request-Headers

CORS OPTIONS preflight response headers

• Access-Control-Allow-Origin
• Access-Control-Allow-Methods
• Access-Control-Allow-Headers
• Access-Control-Max-Age

CORS GET response headers

• Access-Control-Allow-Origin
• Access-Control-Expose-Headers