Creating z/OS Connect APIs

Installing the z/OS® Connect EE API Editor into your Eclipse environment adds a perspective that allows you to create a z/OS Connect EE API Project.

The z/OS Connect EE API Editor is an Eclipse-based workstation tool that you install into IBM® Explorer for z/OS to create REST APIs. Once the editor is installed into your Eclipse environment, a new perspective is available that allows you to create a z/OS Connect EE API Project, using the File > New menu option.

The editor can be downloaded from the IBM Mainframe Developer Center. Documentation for z/OS Connect and the z/OS Connect EE API editor is provided by IBM Knowledge Center.

The API editor allows you to define the URL for your APIs, including path parameters and query strings. For example:

Figure 1. z/OS Connect EE API Editor
Defining a URL in the API editor using path parameters and query strings

Each API must be associated with a service. For Z Data Tools APIs, service archive files called zdtService.sar, zdtIMSService.sar, and zdtDB2Service.sar are provided for this purpose. The service archive files are copied to a location accessible from your Eclipse environment during installation of the Z Data Tools Service Provider for z/OS Connect (see the Z Data Tools Customization Guide).

Alternatively, you can create your own service archives (SAR files) using the provided Z Data Tools Build Toolkit plug-in.

During API creation, you must associate the API with a Z Data Tools service. Click the Service button and navigate to a Z Data Tools service archive file on your file system:

Figure 2. Associating the API with a Z Data Tools service
Associating the new API with the service archive file

You can map data provided by the API caller into the JSON request schema expected by the Z Data Tools Service Provider.

Figure 3. Generic request example: mapping API data in the request schema
Generic request example: mapping data from API call to the request schema

In Figure 3, the path parameters for file name and template name, and the query parameter for timeout, have been mapped to the request schema. API creators can map as little or as much of the request schema as required. Whatever is not mapped must be provided in the HTTP request body by the client issuing the REST API call.

New APIs can be deployed to your z/OS Connect Websphere Liberty Profile (WLP) environment using the z/OS Connect EE > Deploy API to z/OS Connect EE Server menu option.