Request and response mapping rules

Request mapping allows for copying data from the HTTP request context to the service request JSON, while response mapping allows for copying data from the response JSON to the HTTP response context.

Each operation in a z/OS® Connect API is assigned to a service, which provides the implementation (business logic). Therefore, incoming HTTP requests result in a service invocation. While services describe their request and response interfaces in terms of JSON schema, the interfaces of an API operation also include portions of the HTTP context. For example, the HTTP request context includes, among other things, HTTP headers and the URI (for example, /customer/doe?id=1). The URI includes path parameters and query parameters. Because API operations adopt the request and response interfaces of their assigned service, mapping also allows for hiding and setting default values for fields in these interfaces so that only information that is relevant to an operation is exchanged with the API client.

The following information is described:

Types of mapping transforms
Request mapping compatibility
Response mapping compatibility

Types of mapping transforms

There are four general types of transforms: one-to-one, one-sided, one-to-many, and many-to-one.

Note: Only one-to-one and one-sided transforms are supported by the API toolkit.

One-to-one transforms
A one-to-one transform reads from a source element and writes to a target element. An example of a one-to-one transform is one where the value of the source element is copied to the target element.

The Move transform is a one-to-one transform that can be used to copy the value of an HTTP request context element to a field in the service request interface, or to copy the value of a field in the service response field to an element of the HTTP response context. A service interface field that is the target of a Move transform is always suppressed from the request body of the API operation.
One-sided transforms
A one-sided transform does not read from a source element. The following examples are one-sided transforms:
- One where a static, literal value is copied into a target element
- One where the target element is suppressed
- One where the target element is renamed
The mapping editor supports the following transform actions that are one-sided transforms:
- The Assign transform is a one-sided transform that can be used to set a static value for a field in the service request interface, service response interface, or a header in the HTTP response context. By default, a service request or response interface field that is the target of an Assign transform is suppressed from the request or response body of the API operation. Clearing the Omit from interface option in the properties for an Assign transform action would cause the target field to be exposed, but documented to have a default value.
- The Remove transform is a one-sided transform that can be used to suppress fields in service request and response interfaces. Removed service request and response fields are not exposed in the request or response body of the API operation. In addition, removed service request fields are not included in the request JSON passed to the underlying service.
- The Task transform is a one-sided transform that can be used to document work yet to be done in the mapping editor. Other transforms cannot be assigned until a Task transform is removed. Tasks are not executed and therefore have no effect on the mapping result.
One-to-many transforms
A one-to-many transform reads from a single source element and writes to multiple target elements. An example of a one-to-many transform is one where the value of the source element is tokenized using a default or custom delimiter, and the tokens are copied to target elements. Copying of source element tokens is performed in structure order, or a user-defined order.
Many-to-one transforms
A many-to-one transform reads from multiple source elements and writes to a single target element. An example of a many-to-one transform is one where the values of source elements are concatenated using a default, custom, or no delimiter and copied to the target element. Concatenation of source element values is performed in structure order, or a user-defined order.

Request mapping compatibility

The following table describes the request mapping compatibility.

Table 1. Request mapping compatibility
Transform action	Mapping rules
Move	An element of the HTTP request context and a service request interface field can be the source and target of a Move transform if the following conditions are met: The HTTP element is not already the source of another transform. The service field is not already the target of another transform. The service field is not a composite (a field that contains other fields). The service field is not a descendant of a field that is the target of a Remove transform. The HTTP element and the service field have the same array depth (are nested within an identical number of array dimensions). Note: The source element of a Move transform inherits relevant constraints of the target element. For example, if an HTTP header of type string is mapped to a service field of type string, and the service field has a maximum length of 30, the HTTP header will be documented with a maximum length of 30.
Assign	A service request interface field can be the target of an Assign transform if the following conditions are met: The service field is not already the target of another transform. The service field is not a composite (a field that contains other fields). The service field is not a descendant of a field that is the target of a Remove transform. The service field is not an array nor is it a descendant of an array.
Remove	A service request interface field can be the target of a Remove transform if the following conditions are met: The service field is not already the target of another transform. The service field does not have a descendant that is the target of a Remove transform. The service field is not a descendant of a field that is the target of a Remove transform.
Task	A service request interface field can be the target of a Task transform if the following conditions are met: The service field is not already the target of another transform.

Response mapping compatibility

The following table describes the response mapping compatibility.

Table 2. Response mapping compatibility
Transform action	Mapping rules
Move	A service response interface field and an HTTP response context element can be the source and target, respectively, of a Move transform if the following conditions are met: The service field is not already the source of another transform. The HTTP element is not already the target of another transform. The service field is not a composite (a field that contains other fields). The service field and the HTTP element have the same array depth (are nested within an identical number of array dimensions).
Assign	A service response interface field can be the target of an Assign transform if the following conditions are met: The service field is not already the target of another transform. The service field is not a composite (a field that contains other fields). The service field is not a descendant of a field that is the target of a Remove transform. The service field is not an array nor is it a descendant of an array. An HTTP response context element can be the target of an Assign transform if the following conditions are met: The HTTP element is not already the target of another transform.
Remove	A service response interface field can be the target of a Remove transform if the following conditions are met: The service field is not already the target of another transform. The service field does not have a descendant that is the target of a Remove transform. The service field is not a descendant of a field that is the target of a Remove transform.
Task	A service response interface field can be the target of a Task transform if the following conditions are met: The service field is not already the target of another transform.