Create an operation to inquire about an item

The following steps create an operation to inquire about an item in the catalog.

Before you begin

If the inquireSingle.sar file was generated on a different machine, transfer the file, in binary mode, to the workstation where IBM® Explorer for z/OS® is installed.

About this task

The operation is implemented as an HTTP GET request and demonstrates exposing a resource using a path parameter, with assign, move and remove transforms to map to the inquireSingle service.

Procedure

  1. Rename the default Path value to be /items/{itemID} by typing over the existing value, where {itemID} indicates a path parameter whose value will be substituted at runtime.
  2. Remove the POST, PUT and DELETE methods by clicking on the X at the end of the line. This should leave only the GET method allowed for the path /items/{itemID}.
    Screen image of API Editor dialog used to create an API.
  3. Click Service... for the GET method to select the service archive file that defines the service on this API path that will be called by an HTTP GET request.
    The Select a z/OS Connect Service dialog opens.
  4. Click File System and navigate to the location of the inquireSingle.sar file. Select the file and click Open.
    The Import Services dialog opens. Click OK. The inquireSingle service now appears in the Service dialog.
    Screen image of the dialog for selecting a service.
    Click OK. This operation now maps to the inquireSingle service.
    Screen image of the API Editor shows inquireSingle service defined for GET method
  5. From the menu bar, select File > Save.
  6. Click Mapping... for the GET method, then click Open Both Mappings.
    The request and response mapping editors open so that you can define the mapping between the content of the API's HTTP request and response, and the JSON content passed to and from the z/OS Connect (OpenAPI 2) service.
  7. In the request mapping, right click on ca_request_id and click Add Assign transform.
    This assigns a static value to the property in the request JSON payload passed to the service.
    Screen capture showing how the request mappings are defined.
  8. Ensure Assign has focus, so that the Transform - Assign dialog is displayed in the Properties view. On the General tab, set Value to 01INQS.
    This is the value required by the CICS® Catalog Manager application to perform an inquiry on a single catalog item.
  9. Ensure Omit from interface is checked.
    This excludes this property from the HTTP request body for this operation. This value must be set for the CICS Catalog Manager application, but because its value is the same for all requests, it does not need to be exposed to users of the API.
  10. In the request mapping, expand ca_inquire_single. For each of ca_return_code, ca_response_message, and ca_single_item right click the property and click Add Remove transform.
    This excludes these properties from the HTTP request for this operation. These values are not required on the request. They will be populated by the Catalog Manager application and returned in the response.
  11. Connect the path parameter itemID to ca_item_ref_req by dragging from the path parameter itemID to the JSON property ca_item_ref_req.
    This creates a Move transform that copies the value from the path parameter in the HTTP request to the property in the JSON payload passed to the IBM z/OS Connect service.
    Screen image showing request mapping as described in the text.
  12. In the response mapping, for each of ca_request_id and ca_item_ref_req, right click the property and click Add Remove transform.
    This excludes these properties from the HTTP response body for this operation. These properties do not need to be exposed in the response to the API user.
    Screen image showing response mapping as described in the text.
  13. Save the request and response mapping files.