Request Headers
The following HTTP request headers are relevant to all request methods (GET, PUT, POST and DELETE) and are required on all API requests.
Required Request Header Fields
| HTTP Header | Description |
|---|---|
| Host | Specifies the internet host and port number of the HMC to which the request is being directed, as obtained from the original URI specified by the client application. The Web Services API enforces that the header is provided as required by the HTTP protocol, but does not check or use the value of the header. |
| X-API-Session | An opaque string that provides a cryptographically strong identifier of the API session (known as a session id) under which this request is executed. This header is required on all requests that require authentication. The Login operation begins a new HMC session and includes credentials identifying the HMC user for the session. Upon successful authentication, the Login operation returns the value to be used in the X-API-Session header for all subsequent requests of the same session. Failure to include this header on a request requiring authentication results in status code 403 (Forbidden) with reason code 4. Specifying an invalid session id results in status code 403 (Forbidden) with reason code 5. |
| Content-Length | When used in a request, specifies the length of the request body. If omitted, the request is presumed to not contain a body. |
| Content-Type | When used in a request, specifies the MIME media type of the request body contained in the request. This header is required if the Content-Length header is supplied and specifies a non-zero request body length, otherwise status code 400 (Bad Request) will result. |
| Accept | 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 provided 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. If the header is included, it must allow the media types that the operation supports, otherwise the request will fail with HTTP status code 406 (Not Acceptable). |
Optional Request Header Fields
| HTTP Header | Description |
|---|---|
| X-Audit-Memento | The HMC REST Web Services logs each consumer request into its Audit log. The Audit log is formatted using RFC-5424 extended syslog formatting. For each GET, PUT, POST, or DELETE request that is written to the Audit log, if the X-Audit-Memento header has been specified, that value will be placed into the Audit log. The header name will not be placed in the Audit log. |
| X-Client-Correlator | An opaque string that provides a cryptographically strong identifier of the API session (known as a session id) under which this request is executed. This header is required on all requests that require authentication. The Login operation begins a new HMC session and includes credentials identifying the HMC user for the session. Upon successful authentication, the Login operation returns the value to be used in the X-API-Session header for all subsequent requests of the same session. Failure to include this header on a request requiring authentication results in status code 403 (Forbidden) with reason code 4. Specifying an invalid session id results in status code 403 (Forbidden) with reason code 5. |
| If-Match | Supplies a previously received ETag value or wildcard, and enables conditional PUT or POST operations based on a match of the supplied value with the actual value currently known to the server. |
| If-None-Match | Supplies a previous received ETag value or wildcard, and enables conditional PUT or POST operations based on not matching the supplied value. |
| X-HMC-Schema-Version | Specifies the schema version. When specified with an HMC version 1.1.0 against an HMC version 1.2.0, response contains attributes introduced till version 1.1.0. If schema version is not specified, the latest version supported by HMC is returned as a response. |
| X-Transaction-ID | When set by the client code with an alphanumeric value, the transaction ID is logged in the log files for debugging. When the client is not specifying this value, REST server auto generates this value for the incoming request. The main purpose is to filter various logs at once for a single transaction ID, to ease the debugging |