Map the API response fields

Before you begin

The following tasks must be completed:
  1. Starting the z/OS Connect Designer with Docker and importing an OpenAPI definition.
  2. Configuring your connections to Db2.
  3. Create the getEmployee z/OS Asset.
  4. Map the API request to the z/OS Asset.
  5. Define GET /employees/{id} responses.

About this task

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

The responses need to be mapped to the API response fields. In the task Define GET /employees/{id} 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 Operation flow diagram as described Mapping your API and z/OS Assets.
    The Operation flow diagram shows the responses that need to be mapped. An amber exclamation mark icon An amber exclamation mark indicates that the mapping is not defined.

    The OpenAPI definition defines three possible response codes for the GET/employees/{id} operation, 500, 404, and 200. In the following steps, you map the data that is returned from the z/OS Asset to the API responses.
  2. Map the 200 response.
    In the Operation flow diagram, click the 200 response node.

    A 200 response code indicates that the requested employee record was found and the information is returned in an array. The employee record properties need to be mapped to the fields of the API response.

    1. Map the z/OS Asset response input EMPNO to the employeeNumber API response field.
      Start typing EMPNO. A menu of valid names is displayed where you can select EMPNO.
      Figure 1. Mapping the EMPNO z/OS Asset response input.
      Mapping the EMPNO z/OS Asset response input.
    2. In the same way, map the z/OS Asset response input FIRSTNME to the firstName API response field.
      Figure 2. Mapping the FIRSTNME z/OS Asset response input.
      Mapping the FIRSTNME z/OS Asset response input.
    3. Map the z/OS Asset response input LASTNAME to the lastName API response field.
      Figure 3. Mapping the LASTNAME z/OS Asset response input.
      Mapping the LASTNAME z/OS Asset response input.
  3. Optional: Map other fields to the 200 response.

    In the same way as previous steps, you can choose to map the corresponding fields between the z/OS Asset and the API response.

    Figure 4. Mapping all other fields.
    Mapping all other fields.
  4. Map the 404 response.

    In the Operation flow diagram, click the 404 response node.

    A 404 response code indicates that the requested employee record was not found. Configure the 404 response to return a simple message. Type the following text string into the message field: 
    Employee could not be found.

    You do not need to add quotation marks around this string.

    Figure 5. Data mapping for a 404 response
    Data mapping for a 404 response
  5. Map the 500 response.

    In the Operation flow diagram, click the 500 response node.

    A 500 response code indicates an internal server error. Configure the 500 response to return the z/OS Connect error message and the contents of the StatusDescription field by typing the following into the message field: 
    {{$error.message & $zosAssetResponse.body.StatusDescription}}
    Alternatively you can build up the mapping. Click the Insert a mapping icon insert-mapping icon to select the wanted inputs.

    Figure 6. Data mapping for a 500 response
    Data mapping for a 500 response

Results

You have successfully configured the z/OS Asset.

What to do next

You can test your z/OS Asset directly from the z/OS Connect Designer.