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 and 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 the q query API for details). 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
logCorr	string	Y	Log correlator -- used to trace request in logs.	"myReq-1234"
aggFn	symbol	Y	Aggregation function to use.	`myAggFn
timeout	int or long	Y	Timeout in milliseconds (omit to use system default).	10000
cast	boolean	Y	Apply cast on the column names and values of a filter, i.e. accept strings instead of values that need to match the data types.	1b
version	long	Y	Used as an override to call older versions of API. For example to call sql1.	1
sendPartials	boolean	Y	When set to true. Ensures callers get sent back DAP partial results in the case of a failed aggregation. Intended to help debugging aggregation UDAs.	1b

!!! Note on "app prefix":

If you wish to provide custom `opts` that get passed down to your API, title them with `app` as a prefix.

For example, to call `.example.api` and provide it an overridden `logCorr` and a custom option named `appDebug`:

```q
h (`.example.api;enlist[`table]!enlist`trade;`;`logCorr`appDebug!("test-query";1b))
```
Equivalently over HTTP:

```bash
curl -X POST --header "Content-Type: application/json"\
    --header "Accepted: application/json"\
    --data '{"table":"trace","opts":{"logCorr":"test-query","appDebug":true}}'\
    "https://${INSIGHTS_HOSTNAME}/servicegateway/example/api"
```

If you attempt to provide an option that does not start with `app` the query will be rejected.

Response header

DAPs (and Aggs) are required to return a response header in addition to the request payload (see the q query API for details). The response header will contain all custom fields present in the request header and the fields in the following table.

name	type	description	example
rc	short	Return code	0
ac	short	Application code.	0
ai	string	Application information, this may contain additional information in the event of an error.	"Request failed because ..."
corr	guid	Correlator ID of the request.	8c6b8b64-6815-6084-0a3e-178401251b68
logCorr	string	Log correlator - used to trace request in logs.	"myReq-1234"
api	symbol	API name.	`getData
agg	symbol	Host and port of the Agg chosen to aggregate the DAP responses.	`:hostname:1234
refVintage	long	Reference vintage. Can be used by the DAPs to verify the reference vintage (high watermark of the latest reference data update received by the DAP) the RC used when choosing it. A mismatch indicates that the reference vintage changed between when the DAP was selected and when it received the request, which may cause an error in returning the correct data.	2
rcvTS	timestamp	Time the GW received the request.	2021.06.14D08:14:59
http	symbol	Determines encoding (present in the response header only if applicable)	`json
version	long	Used as an override to call older versions of API. For example to call sql1.	1

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 on the error. For example:

// @overview
// This callback function receives a response from executing an API on the Service Gateway.
// The first argument is a header object describing if the request succeeded or failed. The
// second argument is the response payload if the request was successful.
//
// @param hdr {dict}  Response header.
// @param pl  {table} Response payload.
callback:{[hdr;pl]
    log.debug("Response received, logCorr=%s rc=%n ac=%n";;;). hdr`logCorr`rc`ac; / Log details

    // Identify failures and exit early.
    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")

For details on generating response headers in custom aggregations, refer to the UDA helper function guide.