Implementing a REST API operation by using a message map

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 or OpenAPI 3.0 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 or OpenAPI 3.0 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 is 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 requires 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 re-create 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.

If you are implementing a REST API operation in which the processing can be achieved by using the Transform types in the Graphical Data Mapping editor, you can implement the operation by using a single message map, as described in the following procedure. However, if the processing for your REST API operation requires that you transform to an intermediary data format and use additional nodes as part of your implementation, follow the procedure that is described in Implementing a REST API operation with intermediary processing by using message maps.

Procedure

To implement an operation in a REST API by using a single message map, complete the following steps:

  1. 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 or the OpenAPI 3.0 document is current and consistent.
  2. Add a Mapping node to the subflow.
  3. 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.
  4. The REST API operation message map is created in the REST API project and opened in the Graphical Data Mapping editor.
  5. 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.
  6. The message body of the map input and output is also automatically defined by the REST API Swagger document or OpenAPI 3.0 documents.
    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 or OpenAPI 3.0 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 or OpenAPI 3.0 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 or OpenAPI 3.0 document definitions) it has a type name as the model name; for example, Pet or Department. If it is an array of a type that is 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 or an OpenAPI 3.0 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 or an OpenAPI 3.0 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
  7. Complete the required transformation logic in the map 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.