Request and response mapping rules
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.
Types of mapping transforms
- 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 transformsA 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.
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:
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:
|
Remove | A service request interface field can be the target of a Remove
transform if the following conditions are met:
|
Task | A service request interface field can be the target of a Task transform if the following
conditions are met:
|
Response mapping compatibility
The following table describes the 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:
|
Assign | A service response interface field can be the target of an Assign
transform if the following conditions are met:
|
Remove | A service response interface field can be the target of a Remove
transform if the following conditions are met:
|
Task | A service response interface field can be the target of a Task
transform if the following conditions are met:
|