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. To work with APIs, you must install the API Editor component of z/OS Connect Enterprise Edition.
For details about the API Editor, see z/OS Connect Enterprise Edition documentation in IBM Knowledge Center.
There are some slight differences in deploying APIs to z/OS Connect Enterprise Edition for CICS, compared to deploying APIs to a stand-alone 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. This
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 any 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.
- A WEBSERVICE resource definition is required in CICS that matches the name of the Service. The WEBSERVICE encapsulates the WSBind file for the Service.
-
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 Resource (AAR) file as output. This
must be deployed to the Liberty server using the deployment mechanisms provided by
z/OS Connect Enterprise Edition. You
might need to create a suitable directory for the APIs in the work area of the
Liberty server. APIs are deployed to the
/resources/zosconnect/apis directory in the Liberty work
area. If this directory does not already exist, create it. An example usage of
apideploy is as follows:
In the given example, /tmp/ExampleAPI.aar is the location of the Application Archive Resource file that is being deployed, and /u/userid/APPLID/JVMSERVER/wlp/usr/servers/ is the value of the WLP_OUTPUT_DIR property in the JVMSERVER configuration file. This example results in apideploy updating the configuration of the Liberty server that is being used by CICS.apideploy -deploy -a /tmp/ExampleAPI.aar -p /u/userid/APPLID/JVMSERVER/wlp/usr/servers/defaultServer/resources/zosconnect/apis
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.