Mapping the API Response fields

Follow the steps to map the responses from your z/OS® Asset to your API Responses.

Before you begin

The following tasks must be completed:
  1. Prepare the sample IMS application.
  2. Starting the z/OS Connect Designer with Docker Desktop and importing an OpenAPI definition.
  3. Configuring connections to IMS with Docker Desktop and Basic Authentication.
  4. Define the GET operation for the /phonebook/contacts/{lastName} path.
  5. Reusing the phonebook z/OS Asset.
  6. Mapping the API Request to the z/OS Asset.
  7. Defining the PUT /phonebook/contacts/{lastName} responses.

About this task

This topic is applicable to: z/OS Connect Designer
capability Content applicable to
application developers

The z/OS Asset response fields need to be mapped to the API response fields. In the task Defining the PUT /phonebook/contacts/{lastName} responses, you defined the order in which the response codes are checked. The next step is to map the data that is returned for each response code.

Procedure

  1. Open the PUT /phonebook/contacts/{lastName} Operation flow diagram as described Mapping your API and z/OS Assets.
    An amber exclamation mark An amber exclamation mark indicates that the mapping is not defined.
    The OpenAPI definition defines three possible response codes for the PUT /orders operation, 200, 400®, and 500. In the following steps, you map the data that is returned from the z/OS Asset to the API responses.
  2. Map the 200 - OK response.
    1. In the Operation flow diagram, click the 200 response node.

      A 200 response code indicates that the requested contact was found. The contact details need to be mapped to the fields of the API response.

    1. Map the z/OS Asset response output OUT-FIRST-NAME to the firstName API response field.
      Type OUT-FIRST-NAME.
    2. Map the z/OS Asset response output OUT-LAST-NAME to the lastName API response field.
    3. Map the z/OS Asset response output OUT-EXTENSION to the extension API response field.
    4. Map the z/OS Asset response output OUT-ZIP-CODE to the zipCode API response field.
    Figure 1. All phonebook PUT responses mapped.
    All phonebook PUT responses mapped
  3. Map the 404 - Not Found response.
    1. In the Operation flow diagram, click the 404 response node.

      A 404 response code indicates that the requested contact might not be found. Configure the 404 response to return a message to explain that the contact was not found by entering the following into the message field:

      Contact with last name {{$apiRequest.pathParameters.lastName}} was not found in phonebook.
      Figure 2. Inputting message
      Inputting message.
  4. Map the 500 - Internal server error response.
    1. In the Operation flow diagram, click the 500 response node.

      Configure the 500 response to return the z/OS Connect

      error message by typing the following into the message field:
      {{$error.message}}{{$zosAssetResponse.message."IVTNO_OUTPUT-MSG"."OUT-MESSAGE"}}
      Alternatively you can build up the mapping to create a more detailed error message. Click the Insert a mapping icon insert-mapping icon to select the wanted inputs.
      Figure 3. Inputting message
      Inputting message.

Results

The API responses (200, 404, 500) returned by the z/OS Asset are successfully mapped.

What to do next

Testing the PUT /phonebook/contacts/{lastName} operation.