Interpreting time data

API request time data is provided for both API provider and API requester to enable problem determination.

API provider timeouts

When running IBM® z/OS® Connect in asynchronous mode and an API or service request times out, the client receives a 503 HTTP status response but request processing can continue asynchronously. Interceptors are called for the asynchronous request processing. When the asyncRequestTimeout expires for a request, the Data.REQUEST_TIMED_OUT flag is set. The Data.HTTP_RESPONSE_CODE is set to the result of the asynchronous request processing, which might complete successfully. The CICS service provider includes support for the asyncRequestTimeout, so when the asyncRequestTimeout expires for a request, asynchronous processing of the request ends and a request is sent to CICS to purge the transaction, if appropriate.

API requester timestamp data

Table 1 shows how the timestamps are set that enable the calculation of the time spent in IBM z/OS Connect , the time to obtain one or more access tokens for the request and the time for the API endpoint to process the request. For requests that do not use access tokens, DataRequester.TIME_TOKEN_GET_START and DataRequester.TIME_TOKEN_GET_FINISH are not set.

If the request response is a 401 authentication failure, the request is retried once with one or more new tokens. The time between DataRequester.TIME_ENDPOINT_SENT and DataRequester.TIME_ENDPOINT_RECEIVED then includes the time to make both the first and second request to the endpoint and the time to get the new token(s) from the authorization server.

Table 1. Setting of timestamps in API requester flow
Step Timestamp setting and request flow
1 Request sent from communication stub to IBM z/OS Connect .
  • DataRequester.TIME_STUB_SENT set.
2 Request enters IBM z/OS Connect server.
  • DataRequester.TIME_ZOS_CONNECT_ENTRY set.
3 Request authentication, authorization and data transformation.
4 - if access token(s) required If access tokens(s) required for request, start acquisition.
  • DataRequester.TIME_TOKEN_GET_START set.
5 - if access token(s) required Access token(s) obtained from cache or authorization server.
  • DataRequester.TIME_TOKEN_GET_FINISH set.
6 Request sent to endpoint.
  • DataRequester.TIME_ENDPOINT_SENT set.
7 Response received from endpoint.
  • DataRequester.TIME_ENDPOINT_RECEIVED set.
8 - if 401 failure If request received an authentication failure response, new access token(s) obtained from authorization server.
9 - if 401 failure Request sent to endpoint.
  • DataRequester.TIME_ENDPOINT_RECEIVED cleared.
10 - if 401 failure Response received from endpoint.
  • DataRequester.TIME_ENDPOINT_RECEIVED set.
11 Response data transformation.
12 Response returned from IBM z/OS Connect server.
  • DataRequester.TIME_ZOS_CONNECT_EXIT set.
1 Response received in communication stub.