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 and Guidewire-proprietary values for standard 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 Cloud API allows the commit only if the checksum in the header matches the checksum value from PolicyCenter.

For more information, see Lost updates and 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. Cloud API allows the commit only if the header's value has not be submitted by any prior request. The value is stored in the PolicyCenter 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 the 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-FailOnValidationWarnings

Boolean

This can cause certain Job actions to fail if the action throws any validation warnings.

If set to true on a request to quote, bind-only, or bind-and-issue a Job, this will cause the action to fail if there are any validation warnings. (Normally, these actions fail only if there are validation errors.) The default is false.

For more information on Job actions, see Submissions.

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 for the response.

For more information, see Language and locale.

GW-Locale String

This sets the locale for the response.

For more information, see Language and locale.

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 Developer Guide.

GW-ValidateResponseHandling

Boolean

This 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 endpoints.

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

Prefer String

This gives the caller the ability to specify a wait time.

(Note: This is a standard HTTP header. Cloud API supports the following standard values for this header: respond-async and respond-async, wait=T. It also supports one Guidewire-specific value, respond-async, wait-ms=T.)

For more information, see Asynchronous calls.

x-gwre-session String

This controls how related calls are routed on instances of PolicyCenter 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 Sticky sessions 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 the 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.