Skip to content

Header

Pass out-of-bound information as part of an API request/response

The Service Gateway header is a way to pass out-of-bound information as part of an API request/response. This is a dictionary whose keys are symbols, but whose values can be of arbitrary type. A client making an API request to the gateway may optionally augment the request header. A Data Access process (DAP) responding to a request must include a minimal response header, and may include other fields as needed.

Request header

A client can augment the header using the optional opts parameter in the API request. On receiving a request, the gateway mechanically generates a header with default values. In some cases the client can override the default values (see table below). The client can also include additional header fields as needed, which can then be used by the DAP to execute the API.

All fields included in the request header are returned to the caller in the response header, so these fields can also be used by the client process that issued the request on receipt of the results.

All custom client fields must use the app prefix to avoid clashing with existing and future internal KXI header fields.

Below is a table of defined header fields. This list is expected to grow as we implement additional features.

name type overwritable description and example
gw symbol N Host and port of GW responsible for the request

`:hostname:1234
corr guid N Correlator ID of the request

8c6b8b64-6815-6084-0a3e-178401251b68
logCorr string Y Log correlator -- used to trace request in logs

"myReq-1234"
api symbol N API name

`getData
rcSend timestamp N Time the RC issued resources. Used by Agg to determine most recent information.

2021.06.14D08:17:00
numResp long N Number of responses the Agg should receive

3
agg symbol N Host and port of the Agg chosen to aggregate the DAP responses

`:hostname:1234
pvVer long N Purview version number. Can be used by the DAPs to verify the version the RC used when choosing it. A mismatch indicates that the purview changed between when the DAP was selected and when it received the request, which may cause an error in returning the correct data.

1
aggFn symbol Y Aggregation function to use

`myAggFn
timeout int or long Y Timeout in milliseconds: omit to use system default

10000
rcvTS timestamp N Time the GW received the request

2021.06.14D08:14:59
to timestamp N Time the request is set to expire (rcvTS + timeout)

2021.06.14D08:17:09

Response header

DAPs (and Aggs) are required to return a response header in addition to the request payload. The response header must contain, at minimum, the fields present in the request header and the fields marked required in the following table. As with the request header, a client-defined DAP may return additional custom header fields using the app prefix to avoid clashing with existing and future internal KXI header fields.

name required type description and example
rc Y short Return code

0
ac Y short Application code

0
ai N string Application information: may contain additional information in the event of an error

"Request failed because ..."
sendErr N any Presence of this key indicates to the RC that the process was not able to send its response to the intended recipient (DAP to Agg or Agg to GW). This triggers the RC to fail the request and alert the issuing GW of the failure.

`

Using the Response header

When receiving the response from an API call, you can use the response header to log information about the request. In particular, with the RC and AC codes, you can determine whether or not the response was successful and, in the event of a failure, details of the error. For example:

callback:{[hdr;pl]
  log.debug("Response received, logCorr=%s rc=%n ac=%n";;;).
    hdr`logCorr`rc`ac; / Log details

  //
  // Identify failures.
  //
  if[hdr[`rc]<>0h;
    / AI may have additional info
    log.error"Error executing",$[`ai in key hdr;" ",hdr`ai;""];
    ... / Failure logic
    :()]; / Early exit, as the payload is no good

  //
  // Happy path.
  //
  log.debug"Response successful";
  ... / Do something with the payload
  }

neg[gwHandle](`myAPI;myArgs;`callback;enlist[`logCorr]!enlist"myLogCorrelator")