Header

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 GW may optionally augment the request header. A DAP responding to a request is obligated to include a minimal response header, and may add additional fields as needed.

Request header

A client can augment the header using the optional opts parameter in the API request (see "interface""). 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 internal KXI header fields (existing and future).

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

name	type	overwritable	description	example
client	symbol	N	Host and port of client/GW responsible for the request.	`:hostname:1234
protocol	symbol	N	Protocol. gw if going through GW, q for internal q processes.	`gw
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	dictionary	N	Number of responses the Agg should receive for each label combination.	0 1 2 3!2 3 1 2
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
ogRcID	symbol	N	Host/port of RC that originally received this request.	:rcHost:5050
numRP	long	N	Number of label combinations in the request.	4
retryCount	long	N	Number of times this request has been retried.	2
subLevel	long	N	Deferred request depth.	1
cb	symbol	N	Callback for internal q requests.	`myCallbackFn

Response header

DAPs (and Aggs) are required to return a response header in addition to the request payload (see "interface"). The request header must contain, at minimum, the fields present in the request header and the fields labelled "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 internal KXI header fields (existing and future).

name	required	type	description	example
rc	Y	short	Return code (see "SAPI - Codes").	0
ac	Y	short	Application code (see "SAPI - Codes").	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 making 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 on 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;
        log.error"Error executing",$[`ai in key hdr;" ",hdr`ai;""]; / AI may have additional info
        ... / 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;enl[`logCorr]!enl"myLogCorrelator")

Generating a response header in custom aggregation functions

Aggregation functions must return a response header containing, at minimum, rc, ac, and optionally ai. There exist .sapi convenience functions for wrapping results with a response header.

• .sapi.ok - Used the indicate successful completion.

  • Parameters:
    • res - any - Response payload.
  • Output:
    • (dictionary;any) - Successful response header and payload.

• .sapi.hok - Used to indicate successful completion, and add optional header fields to the response.

  • Parameters:
    • hdr - dictionary - Header fields to add to response header.
    • res - any - Response payload.
  • Output:
    • (dictionary;any) - Successful response header and payload.

• .sapi.defer - Used to defer response pending the results of a sub-request.

  • Parameters:
    • api - symbol - API for sub-request.
    • args - dictionary - API arguments.
    • cb - symbol - Callback to invoke on sub-request response.
    • opts - dictionary - Optional header augmentations.
  • Output:
    • (dictionary;list) - Deferred response header and sub-request details.

• .sapi.response - General response function that provides full control over response and application codes.

  • Parameters:
    • hdr - dictionary - Header fields to add to response header.
    • st - list[2]|list[3] - Result status: rc, ac, and optionally ai. See codes for rc and ac values.
    • res - any - Response payload.
  • Output:
    • (dictionary;any) - Response header and payload.

See configuration_sg for example aggregation functions.