Defining responses

Set conditions for your OpenAPI definitions responses.

About this task

zosConnect-3.0 Applies to zosConnect-3.0.

Containers Applies to z/OS Connect container deployments.

The Responses node in the IBM® z/OS® Connect Designer allows a user to define which response is returned by the API. You can set conditions for each response within an API operation.
Important: {{ ... }} double braces must be used to identify the JSONata expression in fields of type String. The (abc) label identifies a string-mapping field. Any text outside the double braces {{ ... }} is treated as a string literal. All other field values are treated as JSONata expressions in which literal text should be quoted.

Procedure

  1. Open the Operation flow diagram as described Mapping your API and z/OS Assets.
  2. Click Responses on the Operation flow diagram.
    Figure 1. Responses
    Screen capture to show the Responses within the Operation flow diagram with the 200 Response selected
    The imported OpenAPI definition defines the responses for the operation. If the responses node has one of the following icons, configuration steps are required.
    • An amber exclamation mark An amber exclamation mark indicates that the response condition is not defined.
    • A red mark A warning icon indicates that a response condition is invalid.
    Responses are evaluated first to last where the final response is the default response. Each response case has the following properties:
    • Each condition has three fields, response, predicate, and value,
    • One or more conditions can be applied. Click Add condition + to add a new condition.
    • The ordering of the responses cases can be changed by using An arrow pointing up icon and An arrow pointing down icon next to each response case.
    • The sequence of the conditions within a response case can be changed. Click A drag vertical icon and then drag the condition up and down the condition sequence order to change its place in the sequence.
    • Conditions can be deleted. Click A trash can icon to delete a condition.
    • When response conditions are matched, the mappings for this response are used. If an error occurs when trying to use these mappings, the mapping sources are updated to remove the zosAssetResponse and to add the error details to the error object. The response conditions mappings are then reevaluated (once only), from first to last. This retry behavior occurs a maximum of one time.
  3. Define the condition for Response 200 - OK.
    Response 200 means that data is successfully returned and the condition can be defined as shown in Figure 2.
    Figure 2. Response 200
    Screen capture to show the Response 200 and how to configure the response field with the predicate and the value
  4. Define the condition for Response 404 - Not Found.
    The Response Field, Predicate, and Value fields are the same as for all Responses. Select the values required for your condition definition. For example, if you'd like to return the 404 not found response when no data is returned in the z/OS Asset response, you can use the $count function. The $count function counts the number of items in an array parameter. 
    $count($zosAssetResponse.body."ResultSet Output")
    By setting Predicate to Equals and the value to 0 you can identify when nothing has been returned in the ResultSet Output as per Figure 3.

    Figure 3. Setting the condition for the 404 Response
    Screen capture to show how to set the condition for the 404 response case.
  5. Define the condition for Response 500 - Internal Server Error.
    Normally, the 500 response would be the default, so it is only necessary to ensure that it is the last response in the table. If you want to define the conditions for the 500 response, use the drop-down option to specify how you want the conditions to be evaluated. There are two options All the following are true indicates that all conditions specified must be true before the 500 response is sent. Any of the following are true indicates that any one of the conditions that are specified must be true before the 500 response is sent. Next, click into the Response Field input box and select the Insert a mapping icon input button to view the Response Field available mapping inputs.
    Figure 4. Response 500 - setting response field input
    Screen capture to show how to set the Response Field input for the 500 response code

    Explore the available inputs as shown in Figure 4. An extension to the example might be to expand the zosAssetResponse mapping and scroll through the list to select statusCode. When the Response Field has been selected, choose the predicate for your condition. In this example, the Equals selection has been kept in the Predicate drop down. Finally, within the Value text box enter the value of 500.

    A summary is displayed to show the condition created, for example, If $zosAssetResponse.statusCode equals 500 then send 500 response for the preceding example.

Results

z/OS Connect has new powerful visual-mapping with JSONata expression language. You can complete complex mappings like splits and joins, and other types of functions that provide flexibility. Find out more about these mapping capabilities here How to use JSONata in the IBM z/OS Connect Designer.

What to do next

Now that you have defined your responses that are returned by the API and set the conditions and data mappings, you can test your conditions by using the test features. Find out more about testing your operation here Test the GET /employees/{id} operation.