How the z/OS Connect Server JSON object is created for mapping

This topic describes the JSON data that is available for use in mapping files for API provider.

zosConnect-3.0 Applies to zosConnect-3.0.

Containers Applies to z/OS Connect container deployments.

The JSON object for request mapping

When a client sends an HTTP request to the z/OS Connect Server, the different parts of that HTTP request are converted into a JSON object for use in mapping. This JSON object is then made available for the request mapping (request.yaml) to the z/OS Asset for the invoked operation. The JSON object contents for request mapping are described in Table 1.

Table 1. JSON object for request mapping
Field Value
headers All headers from the HTTP request. Each header is a child field with a String value. When multiple values are supplied, they are combined into a single String of comma-separated values.
Note: From z/OS Connect 3.0.96, header names will be mapped case insensitively.
queryParameters Any query parameters from the HTTP request. Each query parameter is a child field with a String value unless the Open API document specifies type array in which case an array is used.

When no query parameters are supplied, the JSON object is empty.

When a query parameter has multiple values and is not an array, the message number BAQR1712E is written to the messages.log file and also set as the value for the message field in the error object. The code field is set to 400. For more information, see Table 3.

Note: Before z/OS Connect 3.0.69, when multiple values are supplied they are combined into a single String of comma-separated values.
pathParameters Any path parameters from the HTTP request. Each path parameter is a child field with a String value.

When no query parameters are supplied, the JSON object is empty.
body The JSON body from the HTTP request. The field is Null when no body is supplied.
cookies Any cookies from the HTTP request. Each cookie is a child field with a String value. When multiple values are supplied, they are combined into a single String of comma-separated values.

When no query parameters are supplied, the JSON object is empty.
requestMetadata (From 3.0.71) A JSON object containing metadata about the API request that the server received. See Table 2.
Note: By selecting apiRequest from the mapping sources, this exact JSON object is available in the response-mapping files response_mapping.yaml and response_nnn.yaml.
Table 2. Request Metadata. (From 3.0.71)
Field Value
scheme The scheme for the request. One of http or https.
host The host for the request. For example, ibm.example.com.
port The port for the request. For example, 9443.
uri The URI for the request. For example, /items.
url The full URL for the request. For example, https://ibm.example.com:9443/items?startItemID=10.
queryString The query string for the request. For example, startItemID=10.
method The HTTP method for the request. For example, GET.

The JSON object for response-mapping

When z/OS Connect receives a response from the z/OS Asset, another JSON object is created to represent the original API request, the z/OS Asset response, and error information. The JSON object contents for response mapping are described in Table 3.

Table 3. JSON object for response
Field Value
apiRequest The JSON object created for request mapping. See Table 1.
zosAssetResponse The JSON object that represents the response from the z/OS Asset in use. The content varies per z/OS Asset. For more information about how the content varies per z/OS Asset, see the following tables for Db2®, CICS®, and IMS.

This field contains Null if an error occurred.
error

Two fields are contained in this object:

  1. message - the error message
  2. code - the error code

This field contains Null when no error occurs.
Note: The zosAssetResponse and error fields are mutually exclusive. When one has a value, the other is null.
Db2 - zosAssetResponse
Field Value
headers All headers received from calling the Db2 native REST services. Each header is a child field with a String value. When multiple values are supplied, they are combined into a single String of comma-separated values.
Note: From z/OS Connect 3.0.96, header names will be mapped case insensitively.
body The JSON body received from calling the Db2 native REST services.
cookies Any cookies that are received from calling the Db2 native REST services. Each cookie is a child field with a String value. When multiple values are supplied, they are combined into a single String of comma-separated values.

Empty object when no cookies are supplied.
statusCode The integer HTTP status code that is received from calling the Db2 native REST services. For example, 200 for success.
CICS Channel - zosAssetResponse
Field Value
channel A field for each container that is returned in the Channel from CICS where the field name matches the container name. For each BIT container, the bytes are transformed into JSON. For each CHAR container, the character data is converted into a String.
CICS COMMAREA - zosAssetResponse
Field Value
commarea The bytes received in the COMMAREA from CICS are transformed into JSON.
IMS - zosAssetResponse
Field Value
message The JSON object that represents the response from IMS.