HTTP headers

Request and response objects are used by REST APIs to send information between application. These objects contain HTTP headers. An HTTP header is a name/value pair included with a request or response object that provides metadata about the request or response. An HTTP header can specify information such as:

  • The format used in the request object (such as whether it is JSON or XML)
  • The format to use in the response object
  • Session and connection information
  • Authorization information

Overview of Cloud API headers

Cloud API supports standard HTTP headers, such as Authorization and Content-Type.

Cloud API also supports the following Guidewire-proprietary headers. Every Guidewire-proprietary header is optional.

Header Datatype Description
GW-Checksum String

This can prevent lost updates.

When specified, if the call would result in a database commit, then the API allows the commit only if the checksum in the header matches the checksum value from ClaimCenter.

For more information, see Checksums.

GW-DBTransaction-ID

String of up to 128 characters

This can prevent duplicate requests.

When specified, this is used as the database transaction ID for this request. The system API allows the commit only if the header's value has not be submitted by any prior request. The value is stored in the ClaimCenter database and must be globally unique across all clients, APIs and web services.

For more information, see Preventing duplicate database transactions.

GW-DoNotCommit

Boolean

This can be used to warm up endpoints.

Typically, a caller application specifies this on a dummy POST that is sent prior to any genuine business requests. The POST triggers "warm up" activities for the endpoint, such as loading of Java and Gosu classes. But the header prevents any data from being committed. This request can improve the performance of subsequent requests to that endpoint.

For more information, see Warming up an endpoint.

GW-IncludeSchemaProperty Boolean

This can modify the format of a JSON payload.

When this is set to true, if the operation returns JSON with a defined schema, the $GW-Schema property is added to the root JSON object of the response with the fully-qualified name of the JSON Schema definition for that object. The default is false.

GW-Language String

This sets the language used when processing the request.

For more information, see Globalization.

GW-Locale String

This sets the locale used when processing the request.

For more information, see Globalization.

GW-UnknownPropertyHandling

One of these string values:

  • log
  • reject
  • ignore

This specifies the behavior for handling request payloads with unknown properties. The default behavior is reject.

For more information, see Handling a call with unknown elements.

GW-UnknownQueryParamHandling

One of these string values:

  • log
  • reject
  • ignore

This specifies the behavior for handling URLs with unknown query parameters. The default behavior is reject.

For more information, see Handling a call with unknown elements.

GW-User-Context String

This provides information about the represented user when a service makes a service-for-user or service-for-service call.

For more information, see the Cloud API Authentication Guide.

GW-ValidateResponseHandling

Boolean

Requests that the server performs additional validation of REST API responses against constraints such as maxLength that are declared in the schema. Disabled by default, but may be useful in some contexts for testing or debugging of custom APIs.

For more information, see Validating response payloads against additional constraints.

x-gwre-session String

This controls how related calls are routed on instances of ClaimCenter running in a cluster.

(Note: This header is not exclusive to Cloud API and therefore does not follow the convention of using "GW-" at the start of header names.)

For more information, see Routing related API calls in clustered environments.

X-Correlation-ID String

This permits a customer to trace a request from its initial reception through all of the subsequent applications that were invoked to handle that request.

The actual traceability ID present in the MDC and logs (and returned in the response) is dependent on the implementation of TraceabilityIDPlugin plugin. The default implementation uses this value, if specified, or a generated UID. However, another implementation may always generate a unique ID and log the relationship between these incoming values and the generated UID. This header can be repeated, but the resulting string will just be the comma separated values.

(Note: This header predates the REST API Framework and was created prior to the convention of using "GW-" at the start of header names.)

Send a request with a Cloud API header using Postman

About this task

You can include Cloud API headers in calls executed from Postman.

Procedure

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
  2. Specify authorization as appropriate.
  3. Add the header and header value.
    • In the first row of tabs (the one that starts with Params), click Headers.
    • Scroll to the bottom of the existing key/value list.
    • In the blank row at the bottom of the key/value list, enter the header name in KEY column and its value in the VALUE column.
  4. Enter the request operation and URL.
  5. Click Send.