Using APIs from z/OS Connect Enterprise Edition

A primary feature of z/OS® Connect Enterprise Edition is the ability to compose JSON APIs from one or more JSON services. This capability does not exist in z/OS Connect for CICS® 1.0. For the best API development experience, deploy APIs and services to z/OS Connect Enterprise Edition v3.0, rather than using older JSON web services technology in CICS in compatibility mode. For more information, see the z/OS Connect Enterprise Edition documentation.

For details about the API Toolkit, see z/OS Connect Enterprise Edition V3.0 product documentation.

There are some slight differences in deploying APIs to z/OS Connect Enterprise Edition for CICS, compared to deploying APIs to a standalone installation of z/OS Connect Enterprise Edition. The following considerations apply to deploying APIs to CICS:

  • You cannot adopt an existing WSBind file for use with an API. The API Editor requires one or more Service Archive Resource (SAR) files as part of its input.

    If you use the CICS service provider supplied by CICS TS, the WSBind file is created with the BAQLS2JS or BAQJS2LS assistants that are distributed with z/OS Connect Enterprise Edition. If you want to create APIs, start by generating the required WSBind and SAR files using the assistants that are supplied with z/OS Connect Enterprise Edition.

    You must set the SERVICE-NAME parameter in BAQLS2JS or BAQJS2LS to match the name of the WEBSERVICE resource that will be used in CICS. CICS relies on a one-to-one match between the name of the Service in z/OS Connect, and the name of the WEBSERVICE in CICS.

    If you use the CICS service provider that is supplied with z/OS Connect Enterprise Edition, a SAR file is created with either the service editor in the z/OS Connect Enterprise Edition V3 API Toolkit or the build toolkit that is distributed with z/OS Connect Enterprise Edition. You must use these tools to generate the required SAR files before you can create APIs.

  • A WEBSERVICE resource definition is required in CICS that matches the name of the service.

    If you use the CICS service provider supplied by CICS TS, the WEBSERVICE encapsulates the WSBind file for the service.

    If you use the CICS service provider supplied with z/OS Connect EE V3, a WEBSERVICE resource definition is not required.

  • A URIMAP resource definition may also be provided in CICS. If a URIMAP is used, CICS automatically associates the work for the API with a transaction ID and sets a suitable initial user ID.

  • The API Editor produces an Application archive (AAR) file as output. This must be deployed to the z/OS Connect EE server using the deployment mechanisms provided by z/OS Connect EE. By default, APIs are deployed to the /resources/zosconnect/apis directory in the server's configuration directory. If this directory does not already exist, you must create it, or you might prefer to create an alternative directory for the APIs and specify that on the zosconnect_APIs element in server.xml.

If you follow the considerations above, the API and its component services are deployed to CICS. CICS is configured with suitable URIMAP and WEBSERVICE resources, and the AAR file is deployed into the Liberty configuration work area. The main Liberty configuration file, server.xml, contains an entry for each component service that is deployed.