Examining, testing, starting, and stopping an API

1. In the IBM z/OS Connect Server view, ensure that the server is connected. If the server is not connected, right-click the server and select Connect.
2. Expand the server and the APIs folder to see the deployed APIs to the server.
   To examine the status, version number, API URL, description, and documentation of an API, click the API to see the information in the Properties view.

Interacting with APIs

3. For each API in the z/OS Connect Servers view, you can start, stop, remove, or invoke it.
   • To temporarily stop further requests through the API, right-click the API and select Stop API.
   • To restart the API, right-click and select Start API.
   • To remove an API, the API must be stopped first. After an API is stopped, right-click and select Remove API.
     Tip: You can set the preferences to automatically stop an API upon removal or to automatically start an API upon deployment in the z/OS Connect preferences window.
   • You can examine or invoke an API by using API Explorer or Swagger UI. API Explorer is the preferred method for examining and invoking APIs, because it ensures that you will not encounter cross-origin resource sharing (CORS) failures.
     1. API Explorer - Enable use of the API Discovery feature by adding the apiDiscovery-1.0 element to the feature list in the server configuration file. For more information about API Discovery, see API Discovery (apiDiscovery) in the WebSphere Application Server Liberty documentation.

        <feature>apiDiscovery-1.0</feature>

        To examine and test the operations of the API in the API Explorer hosted from the z/OS Connect Server, double-click the API or select Open API Explorer from the context menu.

        If an API is updated, any changes to its interface will not be visible in the API Explorer until you refresh cached information in the z/OS Connect API toolkit by right-clicking the browser tab and selecting Refresh.

     2. Swagger UI - To examine and test the operations of the API in Swagger UI hosted locally from the z/OS Connect API toolkit, select Open in Swagger UI from the context menu.
        Important: Before you use the Try it out! button in the Swagger UI, if your z/OS Connect Server connection is secure (SSL/TLS), install and trust the server's certificate by using Certificate Manager (Start > Run and select certmgr.msc) in Windows, or by using Keychain Access in macOS. Because Swagger UI runs on a workstation rather than the server where the API is hosted, CORS must be enabled on the server, and the client (Swagger UI) must accept the self-signed certificate. For more information about CORS and related configuration, see Installing and trusting a server certificate for Swagger UI.
        Tips:

        1. You can disable the prompt about a valid TLS certificate if required. From the main menu bar, click Window > Preference > z/OS Connect, and specify your choice.
        2. If you prefer to open the Swagger UI outside of the editor in an external browser, configure your Eclipse preferences by selecting Window > Preference > General > Web Browser, and specify your browser of choice.
        3. If you added custom HTTP headers to your API response, then by default these headers are not displayed in the Swagger UI Response Headers section. To display custom HTTP response headers for your API, you need to add the following attribute to the cors element in your server.xml configuration file:

           exposeHeaders="customHeader1, customHeader2"

           For more information about configuring CORS, see Configuring Cross-Origin Resource Sharing on a z/OS Connect Server.