Optional request headers

Edit online

The following HTTP request headers are relevant to all request methods (GET, PUT, POST, DELETE) and may be specified on these method requests but are not required. If present, they are interpreted by the API in the indicated way.

HTTP header name Rqd/Opt Description
Accept Optional1 Specifies the list of response MIME media types that the client application is prepared to accept for the response to the request. This header is provides for content negotiation between the client and the server in cases where the Web Services API supports multiple possible response media types for a given operation.

In the current implementation, the Web Services API supports only a single response media type for each operation. For the majority of operations, that media type is JSON (application/json), but selected operations support a different media type (indicated in the descriptions of those special operations).

If this header is omitted, the Web Services API responds using the (single) media type supported for the operation. If the header is included, it must allow for the single media type that the operation supports, otherwise the request will fail with HTTP status code 406 (Not Acceptable).

If an operation is extended to support multiple media types, compatibility will be maintained for existing clients that request the operation without specifying an Accept header.
X-Audit-Id Optional2 A string that provides additional client identity information that is included in all audit records created for this request, in addition to the API user's HMC login identity. This header is intended to provide improved audit logging in the case of clients that make requests on behalf of multiple upstream users while logged into the API under a single HMC login identity. Such clients should provide the identity of their upstream user in this header so that the requests of different upstream users can be distinguished in the HMC audit logs. The HMC will use up to the first 64 characters of information from this header if present, and silently ignore the remainder of the header's value if it is longer than 64 characters.
X-Client-Correlator Optional A string that provides diagnostic information pertaining to this request that is of significance to the client, such as a client request number or the like. The HMC will record this information in selected diagnostic trace or log data it collects so as to allow better cross-correlation of this information with similar information maintained by the client. This data supplied in this header is intended to assist in product problem determination and does not otherwise affect the operation of the API. The HMC will use up to the first 64 characters of information from this header if present, and silently ignore the remainder of the header's value if it is longer than 64 characters.
X-API-Target-Name Optional Specifies the name of the target for the request. The value is the name portion of the RACF® profile used for z/OS® permission checking for the request. The value is checked for consistency with the URI of the request and is used internally on the Support Element to route requests to other systems. Must be specified for all BCPii requests except for the /api/cpcs operation for the local system.
Note:
  • 1Not allowed for requests using the BCPii interface.
  • 2For the BCPii interface, this is automatically set by BCPii and contains the user ID associated with the calling program.