Defining your APIs with the z/OS Connect API toolkit

The z/OS Connect API toolkit helps you create an API archive file that describes the configuration of the API and the HTTP methods on the resources that can be called.

zosConnect-2.0 Applies to zosConnect-2.0.

For each path and method combination, you can select an existing z/OS Connect service and specify optional HTTP-to-JSON mappings. The mapping is based on a service archive (.sar) file, which is a compressed collection of files that represent all the information that is needed by a z/OS Connect service provider to install and provide the service, and to enable the service as a JSON asset.

The service archive file is generated by the related tool for each of the z/OS Connect service providers. You can use the z/OS Connect API toolkit to create a service to access CICS®, IMS, or IBM® MQ through their respective service provider. For CICS access through the WebSphere® Optimized Local Adapter (WOLA), you can use the build toolkit.

With the service archive, you can map an HTTP method to a field in the service, or assign a value to a field in the service, by using the z/OS Connect API toolkit. After the mapping is complete, you export the API project into an API archive file.

API archive file

A z/OS Connect API archive file or .aar file, is a compressed file that contains all the files required for the server to install the API.

Note: The contents of the API archive file might change in later releases.

The generated Swagger document in the API archive file is the REST API equivalent of a WSDL document for a SOAP-based web service.

Defining your API in z/OS Connect API toolkit

With the API toolkit, you can complete the following REST API development tasks:

Define an API by specifying a name, some description, the base path, and a version number. The base path is the root of all resources that are associated with this API. The base path can contain a variable.
Define API contact information by specifying a API author name, URL, and email address to provide consumers of the API additional information if support is needed for using the API.
Add or remove one or more paths (relative paths). For each path:
- You can specify a path parameter in the path, which is indicated with curly braces ({}), such as:
```
/myPath/{myVariable}
```
- You can add and remove HTTP methods.
- You can reorder methods.
- Each method can be associated with:
  - A z/OS Connect service
  - One or more query parameters
  - One or more headers
- For each method, you can specify the following actions:
  - Assign a static value to a field.
  - Assign a value to a field from the header, path parameter, or query parameter.
  - Remove a field.

After the HTTP-to-JSON mapping is defined, you can deploy the API to the z/OS Connect server. From the API toolkit, right-click the API, then click z/OS Connect > Deploy API to z/OS Connect Server.

Testing, starting, and stopping an API

After an API is deployed, you can single-click the API in the z/OS Connect Servers view to examine its properties. You can further use the provided Swagger UI to examine and test the operations in the API by double-clicking the API in the z/OS Connect EE Servers view. You can also start or stop a deployed API, or remove an API from the server, all from within the API toolkit: