Skip to content

Reading REST Response Headers

The default qie.callRESTWebService(...) returns only the response body as a string, which is fine when a script needs nothing else. When the script also needs the HTTP status code, response headers (e.g. rate-limit counters, pagination cursors, custom X- values), or a binary body it can decode itself, pass true for the returnFullHttpResponse argument (position 8). The call then returns an XML envelope containing status, headers, and content, which the script can query with normal HPath.

What "full response" actually returns

With returnFullHttpResponse = true, the return value is an XML string with this exact shape:

<httpResponse>
  <responseStatus>
    <statusCode>200</statusCode>
    <reasonPhrase>OK</reasonPhrase>
    <protocolVersion>HTTP/1.1</protocolVersion>
  </responseStatus>
  <headers>
    <header name="Content-Type"><![CDATA[application/json; charset=utf-8]]></header>
    <header name="X-Claimable"><![CDATA[105]]></header>
    <header name="X-Awaiting"><![CDATA[406]]></header>
  </headers>
  <content>eyJwaXBlbGluZVJ1blN0ZXBJRCI6Nzg3OTN9</content>
</httpResponse>

Two details to hold on to:

  • Headers are elements with a name attribute: <header name="X-Claimable">value</header>, not <X-Claimable>value</X-Claimable>. Read a header by attribute predicate: /httpResponse/headers/header[@name='X-Claimable'].
  • <content> is Base64-encoded unless the call also used streamToFile, in which case <content> holds the file path instead. Decode with qie.base64DecodeToBytes before using the body as text or bytes.

Do not confuse it with the channel debug log

When channel debug logging is on, QIE writes a text block starting with Rest Response: followed by Status:, Response Time:, and a Headers: list into the channel log. That text is only for the log. It is not what the script receives. The script always gets the XML envelope above.

Reading a header and the body

var params = qie.newParameterMap();

var fullResponse = qie.callRESTWebService(
   'MyRestConnection',
   qie.getWsEndpointUrl('MyRestConnection') + 'api/claim',
   'POST',
   '{"worker":"my-worker"}',
   'application/json',
   params,
   60000,
   true          // returnFullHttpResponse
);

var response    = qie.parseXMLString(fullResponse);
var statusCode  = response.getNode('/httpResponse/responseStatus/statusCode');
var xClaimable  = response.getNode("/httpResponse/headers/header[@name='X-Claimable']");
var bodyBytes   = qie.base64DecodeToBytes(response.getNode('/httpResponse/content'));
var bodyString  = new java.lang.String(bodyBytes, 'UTF-8');
var bodyJson    = qie.parseJSONString(bodyString);

messageCache.setValue('xClaimable', xClaimable);
messageCache.setValue('pipelineRunStepID', bodyJson.getNode('/pipelineRunStepID'));

The [@name='...'] predicate works on any QIE XML message model, so no special parsing is required to reach a header by name.

When to use it

Use the full response when the script needs:

  • The HTTP status code (e.g. treat 204 differently from 200).
  • A response header value (pagination cursor, Retry-After, custom counter).
  • Access to a binary body it decodes or writes to disk itself.

If the script only needs the response body as text, leave the argument off (or pass false). callRESTWebService returns the decoded body directly, and no XML wrapper needs to be parsed.