IBM z/OS Connect

https://www.ibm.com/docs/en/zos-connect/3.0.0
Admin
IBM z/OS Connect facilitates the creation, exposure, and consumption of APIs for z/OS applications,...
Tokens:1,651,744
Snippets:9,414
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### Example Response for Installed API Requesters

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=application-deploying-api-requester-zos-connect-server

This is an example JSON response received after successfully querying the installed API requesters. It provides details such as the requester's name, version, description, status, and API requester URL.

```json
{
  "apiRequesters": [
    {
      "name": "catalogmanager_1.0.0",
      "version": "1.0.0",
      "description": "API for the CICS catalog manager sample application.",
      "status": "Started",
      "apiRequesterUrl": "http://{host}:{port}/zosConnect/apiRequesters/catalogmanager_1.0.0",
      "connection": "RemoteAPIconn"
    }
  ]
}
```

--------------------------------

### Example Input for startItemID

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=path-test-get-items-operation

This code snippet shows an example input value for the 'startItemID' query parameter when testing the GET /items operation. This value is used to specify which item to retrieve from the catalog.

```text
10
```

--------------------------------

### z/OS Console Messages During z/OS Connect Server Startup

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=server-system-automation

This section displays example messages that are written to the z/OS console when an IBM z/OS Connect server starts with a deployed API. It includes messages indicating server launch, successful API archive installation, server readiness, and web module binding. Note that `BAQR7000I` is specific to z/OS Connect z/OSConnect-2.0.

```text
N 4000000 MVxx     yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKE0001I: The server serverName has been launched.                                               
N 4000000 MVxx     yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +BAQR7000I: z/OS Connect API archive file apiName installed successfully.      
N 4000000 MVxx     yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKF0011I: The server serverName is ready to run a smarter planet.    
N 4000000 MVxx     yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +SRVE0250I: Web Module z/OS Connect has been bound to default_host.    
M 4000000 MVxx     yyddd hh:mm:ss.sss JOBnnnnn nnnnnnnn +CWWKT0016I: Web application available (default_host):            
E                                         870 nnnnnnnn   http://hostname:port/
```

--------------------------------

### Successful API Requester Response Example

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=cafiza-deploying-api-requester-zos-connect-server

This is an example of the JSON response received when an API requester is installed correctly on the IBM z/OS Connect server. It details the name, version, description, status, URL, and connection of the API requester.

```json
{
  "apiRequesters": [
    {
      "name": "contacts_1.0.0",
      "version": "1.0.0",
      "description": "This is an API for managing contacts.",
      "status": "Started",
      "apiRequesterUrl": "http://{host}:{port}/zosConnect/apiRequesters/contacts_1.0.0",
      "connection": "RemoteAPIconn"
    }
  ]
}
```

--------------------------------

### GET /zosConnect/services

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=interface-get-list-services

Retrieves a list of all installed IBM z/OS Connect services and their basic information. Services are included whether they are started or stopped.

```APIDOC
## GET /zosConnect/services

### Description
Gets a list of the IBM z/OS Connect services installed in the runtime, including some basic information. Services are included in the list whether they are started or stopped.

### Method
GET

### Endpoint
/zosConnect/services

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Body
This endpoint does not accept a request body.

### Request Example
None

### Response
#### Success Response (200)
- **zosConnectServices** (array) - An array of objects, where each object represents a z/OS Connect service.
  - **ServiceName** (string) - The name of the service.
  - **ServiceDescription** (string) - A brief description of the service.
  - **ServiceProvider** (string) - The provider of the service.
  - **ServiceURL** (string) - The URL to access the service.

#### Response Example
```json
{
    "zosConnectServices": [
        {
            "ServiceName": "recordOpsCreate",
            "ServiceDescription": "Creates a new record",
            "ServiceProvider": "SAMPLE-1.0",
            "ServiceURL": "https://host:port/zosConnect/services/recordOpsCreate"
        },
        {
            "ServiceName": "recordOpsDelete",
            "ServiceDescription": "Deletes an existing record",
            "ServiceProvider": "SAMPLE-1.0",
            "ServiceURL": "https://host:port/zosConnect/services/recordOpsDelete"
        },
        {
            "ServiceName": "patient",
            "ServiceDescription": "Patient lookup service",
            "ServiceProvider": "imsmobile-2.0",
            "ServiceURL": "https://host:port/zosConnect/services/patientService"
        }
    ]
}
```
```

--------------------------------

### Directory Structure for Sample API

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=api-explore-finished-cics-catalog-manager-project

Illustrates the initial directory structure of a sample API project, including 'finish', 'start', and configuration files.

```shell
/sample-cics-api
|—- /finish
|—- /start
|—- CatalogManagerApi.yaml
|—- license.txt
|—- README.md

```

--------------------------------

### API Status Change Response Body Example (GET)

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=interface-change-status-api

This JSON structure illustrates the response format when retrieving API status using a GET request. It is similar to the PUT response but specifically shows the current status of the API, which can be 'Started' or 'Stopped'.

```json
{
  "name": "API name",
  "version": "version",
  "description": "API description",
  "status": "Started|Stopped",
  "apiUrl": "API base path",
  "documentation": {
    "swagger": "API Swagger document location"
    }
  }
```

--------------------------------

### Verify Installed API Requesters with HTTP GET Request

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=application-deploying-api-requester-zos-connect-server

This HTTP GET request is used to list all installed API requesters on the IBM z/OS Connect server. It helps in verifying the successful installation of new API requesters by checking their status and details.

```http
http://{host}:{port}/zosConnect/apiRequesters
```

--------------------------------

### zconsetup Command: Install Product Extensions

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=reference-command

Initializes IBM z/OS Connect product extensions by creating the necessary product extension directories. This command is only applicable to z/OS Connect installations managed by SMP/E.

```shell
zconsetup install
```

--------------------------------

### Example bootstrap.properties for Server 1

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=configuration-splitting-server-information

This is an example of the bootstrap.properties file for server1, defining specific WOLA parameters. These properties are then referenced in the server.xml to configure WOLA uniquely for this server.

```properties
wola_dgn=ZC1DGN
wola_ndn=ZC1NDN
wola_svn=ZC1SVN
```

--------------------------------

### Create z/OS Connect Server Instance

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=application-creating-deploying-api-requester-tutorial

This command creates a z/OS Connect Server instance named 'server1' using a specific server template. Ensure the `<installation_path>` is correctly set to your z/OS Connect EE installation directory. This is a foundational step for deploying and running the tutorial.

```shell
<installation_path>/bin/zosconnect create server1 --template=zosconnect:sampleApiRequesterRedbooks
```

--------------------------------

### Retrieve Resource Representation using GET

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=apis-designing-restful

Shows an example of an HTTP GET request used for retrieving a resource representation after it has been created. This adheres to REST principles by using GET solely for data retrieval.

```http
HTTP GET request  GET /users/Robert HTTP/1.1
   Host: myserver
   Accept: application/json 
```

--------------------------------

### List Installed API Requesters

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=application-deploying-api-requester-zos-connect-server

This endpoint allows you to list all installed API requesters on the IBM z/OS Connect server. It requires an HTTP GET request to the specified endpoint.

```APIDOC
## GET /zosConnect/apiRequesters

### Description
Retrieves a list of all installed API requesters on the IBM z/OS Connect server.

### Method
GET

### Endpoint
/zosConnect/apiRequesters

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
GET http://{host}:{port}/zosConnect/apiRequesters
```

### Response
#### Success Response (200)
- **apiRequesters** (array) - A list of API requester objects.
  - **name** (string) - The name of the API requester.
  - **version** (string) - The version of the API requester.
  - **description** (string) - A description of the API requester.
  - **status** (string) - The current status of the API requester (e.g., "Started").
  - **apiRequesterUrl** (string) - The URL to access the specific API requester.
  - **connection** (string) - The connection name associated with the API requester.

#### Response Example
```json
{
  "apiRequesters": [
    {
     "name": "catalogmanager_1.0.0",
     "version": "1.0.0",
     "description": "API for the CICS catalog manager sample application.",
     "status": "Started",
     "apiRequesterUrl": "http://{host}:{port}/zosConnect/apiRequesters/catalogmanager_1.0.0",
     "connection": "RemoteAPIconn"
    }
   ]
}
```
```

--------------------------------

### Example bootstrap.properties for Server 2

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=configuration-splitting-server-information

This is an example of the bootstrap.properties file for server2, defining specific WOLA parameters. These properties are then referenced in the server.xml to configure WOLA uniquely for this server.

```properties
wola_dgn=ZC2DGN
wola_ndn=ZC2NDN
wola_svn=ZC2SVN
```

--------------------------------

### GET /apis

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=apis-using-restful-administration-interface

Retrieves a list of all installed IBM z/OS Connect APIs.

```APIDOC
## GET /apis

### Description
Retrieves a list of all installed IBM z/OS Connect APIs.

### Method
GET

### Endpoint
/apis

### Parameters
#### Query Parameters
None

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **apis** (array) - A list of API objects, each containing details about an installed API.

#### Response Example
```json
{
  "apis": [
    {
      "name": "SampleApi1",
      "version": "1.0.0",
      "status": "active"
    },
    {
      "name": "AnotherApi",
      "version": "2.1.0",
      "status": "inactive"
    }
  ]
}
```
```

--------------------------------

### Verify z/OS Connect MDB Deployment Logs

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=ciazcca-configuring-ims-access-zos-connect-using-ims-transaction-manager-resource-adapter

These log messages indicate the successful installation and startup of the IMS TM Resource Adapter and the z/OS Connect Message Driven Bean (MDB). They confirm the adapter is installed, the application is starting and has started successfully, and the MDB has been activated and initialized. Absence or discrepancies in these messages suggest a configuration issue.

```log
J2CA7018I: Installing resource adapter IMSTMRA.
J2CA7001I: Resource adapter IMSTMRA installed in 5.697 seconds.
CWWKZ0018I: Starting application zOSConnectTMRA.
CNTR4000I: The ConnectMDB.jar EJB module in the zOSConnectTMRA application is starting.
CNTR0180I: The ConnectMDB message-driven bean in the ConnectMDB.jar module of the zOSConnectTMRA application is bound to the eis/ConnectMDB activation specification.
CNTR4001I: The ConnectMDB.jar EJB module in the zOSConnectTMRA application has started successfully.
CWWKZ0001I: Application zOSConnectTMRA started in 5.582 seconds.
J2CA8801I: The message endpoint for activation specification eis/ConnectMDB and message driven bean application zOSConnectTMRA#ConnectMDB.jar#ConnectMDB is activated.
BAQR2151I: ConnectMDB version 3.0.94 has initialised.
```

--------------------------------

### Example z/OS Connect API Deployment Response

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=interface-deploying-api

An example of the JSON response received after successfully deploying an API to IBM z/OS Connect. This illustrates the format and typical values for the API details.

```json
{
   "name": "testHealthApi2",
   "version": "1.0.0"
   "description": "Health API",
   "status": "Started",
   "apiUrl": "http://192.0.2.0":9080/testHealthApi2",
   "documentation": {
      "swagger": "http://192.0.2.0":9080/testHealthApi2/api-docs"
    }
 }

```

--------------------------------

### Example of Path-Based API Versioning

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=apis-assign-versions

Demonstrates how to assign versions to API resources using different paths within the same API project. This example illustrates GET requests for different versions of a 'customers' resource and a PUT request for 'accounts'.

```text
My API Project (basepath= /myapi):
GET /myapi/customers this might call service getCustomers
GET /myapi/customers/v2 this might call service getCustomersV2
GET /myapi/customers/v3 this might call service getCustomersV3
PUT /myapi/accounts this might call service updateAccounts
```

--------------------------------

### z/OS Connect Server DEV Logging Format Example

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=server-starting-stopping-zos-connect-servers

This example demonstrates the output format for the 'DEV' logging level in z/OS Connect Server. It shows a sample log message indicating server launch.

```log
[AUDIT ] CWWKE0001I: The server zOSConnServer has been launched.

```

--------------------------------

### EmployeesAPI - Get Employees

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=tutorials-creating-simple-openapi-30-document

This section details the '/employees' GET endpoint for retrieving a list of employee records. It specifies the success response format, including the expected data types and examples for employee details.

```APIDOC
## GET /employees

### Description
Retrieves a list of employee records. Uses the getEmployees Db2 z/OS asset.

### Method
GET

### Endpoint
/employees

### Parameters

#### Query Parameters

(No query parameters defined)

#### Request Body

(No request body defined)

### Request Example

(No request example provided)

### Response
#### Success Response (200)
- **employeeNumber** (string) - Example: "000150"
- **firstName** (string) - Example: "BRUCE"
- **lastName** (string) - Example: "ADAMSON"
- **salary** (number) - Example: "25280"

#### Response Example
{
  "example": "{\"employeeNumber\": \"000150\", \"firstName\": \"BRUCE\", \"lastName\": \"ADAMSON\", \"salary\": \"25280\"}"
}
```

--------------------------------

### Running Container Example Output

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=api-explore-finished-cics-catalog-manager-project

Example output from 'docker ps' indicating a successfully running z/OS Connect Designer container.

```shell
CONTAINER ID    IMAGE              COMMAND         CREATED       STATUS       PORTS                      NAMES
f73c93115331    icr.io/zosconnect/ibm-zcon-designer .             “/opt/ibm/helpers/ru…”  4 seconds ago    Up 2 seconds    0.0.0.0:9080->9080/tcp, 0.0.0.0:9443->9443/tcp  zcworkspace_zosConnect_1

```

--------------------------------

### z/OS Connect Server SIMPLE Logging Format Example

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=server-starting-stopping-zos-connect-servers

This example shows the output for the 'SIMPLE' logging format in z/OS Connect Server. It includes a timestamp, thread ID, module, log level, and the server launch message.

```log
[5/22/23 10:46:20:668 GMT] 0000000b com.ibm.ws.kernel.launch.internal.FrameworkManager A CWWKE0001I: The server zOSConnServer has been launched.

```

--------------------------------

### Example z/OS Connect Service Response (GET)

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=services-creating-ims-database-service

This JSON structure represents a typical response body received after a successful HTTP GET request to a z/OS Connect service. It includes service metadata and status information.

```json
{
  "zosConnect": {
    "serviceName": "<yourService>",
    "serviceDescription": "",
    "serviceProvider": "DBSP-1.0",
    "serviceURL": "https://host:port/zosConnect/services/<yourService>",
    "serviceInvokeURL": "https://host:port/zosConnect/services/<yourService>?action=invoke",
    "dataXformProvider": "jsonByte-1.0",
    "serviceStatus": "Started"
  },
  ....
}
```

--------------------------------

### Example API Details Response

Source: https://www.ibm.com/docs/en/zos-connect/3.0.0/index_topic=interface-get-details-api

This is an example of the JSON response returned when successfully retrieving details for a specific IBM z/OS Connect API using the HTTP GET method. It illustrates the populated fields based on a sample 'HospitalAPI'.

```json
{
  "name":"HospitalAPI",
  "version":"1.0.0",
  "description":"API for Hospital app",
  "status": "Started",
  "apiUrl":"http://localhost:9080/hospital",
  "documentation": {
    "swagger":"http://localhost:9080/hospital/api-docs"
  },
  "services": [
    {
      "name": "patient",
      "uri": "http://localhost:9080/zosConnect/services/patient"
    }
  ]
}
```
Tokens:
Raw