### 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 `` is correctly set to your z/OS Connect EE installation directory. This is a foundational step for deploying and running the tutorial. ```shell /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": "", "serviceDescription": "", "serviceProvider": "DBSP-1.0", "serviceURL": "https://host:port/zosConnect/services/", "serviceInvokeURL": "https://host:port/zosConnect/services/?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" } ] } ```