Implementing a REST API operation with intermediary processing by using message maps

You can use the Graphical Data Mapping editor to implement a REST API operation. When you create a map for a REST API operation, you can choose to have the map input and output defined automatically from the definitions in the REST API swagger document.

About this task

When you create the map for a Mapping node in a subflow that implements a REST API operation, you can select the option Message map with input and output for REST API operation operation_name. When you select this option, the map is created with the input and output data fully defined by the JSON schema data definitions in the REST API swagger document.

The local environment is automatically added to the map input and any path or query parameters are added under Local Environment > REST > Input > Parameters, ready for you to connect transforms. A Task transform is pre-wired to Local Environment > REST > Input, to help you locate this information.

The map input message body is populated according to the operation request body, and the output message body is populated according to the response body. When the body is defined as a model or JSON array, the map is created with a JSON domain message. When there is no body, or a simple type the map is created with a BLOB domain message.

Note: If you update the REST API and change either the path or query parameters, or the request or response body, the message map will be updated automatically to reflect the new definitions when it is reopened. If existing transforms were wired, they might become invalid or disconnected and the map will require modification to match the new data model. If the map was created when there was no request or response body defined for the operation, you must recreate the map to add one later.

Ensure that you are aware of the requirements for JSON schema with message maps. For more information, see JSON schema requirements for message maps.

The following procedure describes the steps that you need to follow if you are implementing a REST operation that involves transforming to an intermediary data format as part of its processing. This is the case if your flow contains nodes that use a different message model from the one that is defined in the REST API. In this situation, you need to use a Mapping node at the beginning of the REST API operation subflow and another Mapping node at the end of the subflow. The first Mapping node takes the REST input from the Swagger document and transforms it to an intermediary format to be used by your processing nodes. At the end of the subflow, the second Mapping node is required to transform from the intermediary format to the format required by the REST API operation response.

To summarize the sequence of events:

Transform from the message format of the REST API operation request to the format of the intermediary processing input (format X)
Process data using message format X and, when it is completed, return the format of the intermediary processing result (format Y)
Transform from message format Y to the format required by the REST API operation response.

Note: If you are implementing a REST API operation in which all the processing can be achieved by using the Transform types in the Graphical Data Mapping editor, you can use a single message map, by following the procedure described in Implementing a REST API operation by using a message map.

Procedure

To implement a REST API operation that involves intermediary processing to transform between data formats, complete the following steps:

Create or open the subflow for the REST API operation.
The REST API must be saved before a new message map for an operation can be created; this ensures that the required information in the swagger document is current and consistent.
Add a Mapping node to the subflow.
Create the message map by double-clicking the Mapping node to open the New Message Map wizard. The wizard detects that the map is being created for the current REST API operation, and preselects the option Message map with input and output for REST API operation operation_name. Click Finish.
The REST API operation message map is created in the REST API project and opened in the Graphical Data Mapping editor.
The input data from the REST API is provided in the map. This is located in the Local Environment, which is automatically added to the map input. Any REST API path or query parameters defined for the operation are automatically defined under Local Environment > REST > Input > Parameters.
A Task transform is added to the map with its input connected to Local Environment > REST > Input, and enables you to locate the REST API input data that might be required in the mappings. You can remove the Task when you have completed your mappings. The map can be deployed and run with a Task transform, with no effect.
Note: Input form and array type parameters are not supported.
The message body of the map input and output is also automatically defined by the REST API swagger document.
The input message body is defined as one of the following types:
- JSON, with the data type of any request body defined for the operation in the Swagger document
- BLOB, when the operation has no request body data
The ouput message body is defined as one of the following types:
- JSON, with the data type defined for the HTTP status 200 response. If there is no status 200 response, either the default response or the first response defined in the swagger document is used.
- BLOB, when the operation has no response body data.
The Data type of the JSON input or output is defined in the following way:
- If the REST API operation request or response is defined as a model type (JSON reference to a type in the swagger document definitions) it has a type name as the model name; for example, Pet or Department. If it is an array of a type defined in the model, the type name is prefixed with JSONArray_; for example, JSONArray_Pet.
- If the API operation request body is defined inline by a swagger schema statement, its type name is formed as:
```
<Json type>_<operation name>_body
```
- If the API operation response body is defined inline by a swagger schema statement, its type name is formed as:
```
<Json type>_<operation name>_<http status code>   
```
  For example:
  string_getSurname_200
  or
  object_getItem_200
- If the request or response body is defined as an inline array, the type name is prefixed with JSONArray_; for example, JSONArray_string_getAllSurnames_200
Select and delete the output message assembly that was created in the map.
Click the Add an output object button in the editor to add the required map output, and select the required message format of the input to the intermediary processing (format X in the example used earlier in this topic).
The message format can be any of the supported formats described in Input and output messages to a message map.
Note: If the format is defined in a JSON schema model, the JSON schema file must be placed in the REST API project container.
Add a second Mapping node as described in Steps 2 and 3.
Select and delete the input message assembly that was created in the map.
Click the Add an input object button in the editor to add the required map input, and select the required message format for the result of the intermediary processing (format Y in the example used earlier in this topic).
The message format can be any of the supported formats described in Input and output messages to a message map.
Note: If the format is defined in a JSON schema model, the JSON schema file must be placed in the REST API project container.
Complete the required transformation logic in the message maps to implement the REST API operation, using any of the Transform types in the Graphical Data Mapping editor. For more information, see Editing message maps.
In addition to transforming the message data, you can interact with resources as described in the following topics:

What to do next

Deploy the REST API with the message map and exercise the operation to verify that the output message is as you expected. For more information, see Troubleshooting a message map.