Using API Catalog

As an application developer, use the API Catalog to view what services are running in the API Mediation Layer. Through the API Catalog, you can also view the associated API documentation corresponding to a service, descriptive information about the service, and the current state of the service. The tiles in the API Catalog can be customized by changing values in the apiml.catalog.tile section defined in the application.yml of a service. A microservice that is onboarded to the API Mediation Layer and configured appropriately, registers automatically with the API Catalog and a tile for that service is added to the Catalog.

Note: For more information about how to configure the API Catalog in the application.yml, see: Add API Onboarding Configuration.

API Versioning

See API Catalog and Versioning for more information about the API versioning.

View Service Information and API Documentation in the API Catalog

Use the API Catalog to view services, API documentation, descriptive information about the service, the current state of the service, service endpoints, and detailed descriptions of these endpoints.

Note: Verify that your service is running. At least one started and registered instance with the Discovery Service is needed for your service to be visible in the API Catalog.

Follow these steps:

1. Use the search bar to find the service that you are looking for. Services that belong to the same product family are displayed on the same tile.

   Example: Sample Applications, Endevor, SDK Application

2. Click the tile to view header information, the registered services under that family ID, and API documentation for that service.

   Notes:

   • The state of the service is indicated in the service tile on the dashboard page. If no instances of the service are currently running, the tile displays a message that no services are running.

   • At least one instance of a service must be started and registered with the Discovery Service for it to be visible in the API Catalog. If the service that you are onboarding is running, and the corresponding API documentation is displayed, this API documentation is cached and remains visible even when the service and all service instances stop.

   • Descriptive information about the service and a link to the home page of the service are displayed.

     Example:

     

3. Select the version (v1, v2) to view the documentation of a specific API version.

   Example:

   
   

4. Expand the endpoint panel to see a detailed summary with responses and parameters of each endpoint, the endpoint description, and the full structure of the endpoint.

   Example:

   

   Notes:

   • If a lock icon is visible on the right side of the endpoint panel, the endpoint requires authentication.

   • The structure of the endpoint is displayed relative to the base URL.

   • The URL path of the abbreviated endpoint relative to the base URL is displayed in the following format:

     Example:

     /{yourServiceId}/api/v1/{endpointName}

     The path of the full URL that includes the base URL is also displayed in the following format:

     https://hostName:basePort/{yourServiceId}/api/v1/{endpointName}

     Both links target the same endpoint location.

Swagger "Try it out" functionality in the API Catalog

The API Catalog enables users to call service APIs through the Try it out functionality. There are 2 types of endpoints:

• Public endpoints

  Endpoints that are accessible without entering user credentials.

• Protected endpoints

  Endpoints that are only accessible by entering user credentials. These endpoints are marked with a lock icon.

  Example:

  

  Note: Before making requests to protected endpoints, authorize your session by clicking the lock icon and complete the required information in the Authorization modal shown below:

  Example:

  

To demonstrate Try it out, we use the example of the Swagger Petstore.

Example:

Make a request

This section outlines the process for making a request.

Follow these steps:

1. Expand the POST Pet endpoint.

2. Click Try it out.

   Example:

   

   After you click Try it out, the example value in the Request Body field becomes editable.

3. In the Example Value field, change the first id value to a random value. Change the second name value to a value of your choice, such as the name of a pet.

4. Click Execute.

   Example:

   

   The API Catalog Swagger UI submits the request and shows the curl that was submitted. The Responses section shows the response.

   Example:

   

Swagger Code Snippets functionality in the API Catalog

As part of the Try it out functionality, the API Catalog provides Code Snippets in different languages for each service API operation. The following languages are supported:

• C
• C#
• Go
• Java
• JavaScript
• Node.js
• PHP
• Python
• cURL

Each of these languages supports a specific HTTP Snippet library (i.e. Java Unirest, Java okhttp etc.).

The basic code snippets provide REST API call samples. To show to the user the real usage of the SDKs, the service onboarder can specify a customized snippet as part of the service configuration:

Example:

apiInfo:  -   apiId: zowe.apiml.discoverableclient.rest      version: 1.0.0      gatewayUrl: api/v1      swaggerUrl: ${apiml.service.scheme}://${apiml.service.hostname}:${apiml.service.port}${apiml.service.contextPath}/v3/api-docs/apiv1      documentationUrl: https://www.zowe.org      defaultApi: true      codeSnippet:        - endpoint: /greeting          language: java          codeBlock: |            System.out.println("Greeting code snippet");        - endpoint: /{yourName}/greeting          language: javascript          codeBlock: |            console.log("Your name greeting code snippet");

Example:

Generate the code snippets

This section outlines the process for generating code snippets.

Follow these steps:

1. Click Try it out and execute the request, as described in the previous section.

2. The API Catalog generates the basic code snippets, shown under the code snippet tab. If the service onboarder has also provided customized code snippets, these snippets are displayed in the snippet bar under a title prefixed with Customized.

   Example:

   

Static APIs refresh functionality in the API Catalog

The API Catalog enables users to manually refresh static service APIs. Use the Refresh Static APIs option if you change a static service API and want these changes to be visible in the API Catalog without restarting the Discovery Service.

Example:

To refresh the status of a static service, click the Refresh option located in the upper right-hand side of the API Catalog UI. Successful requests return a pop-up notification that displays the message, The refresh of static APIs was successful!.

Example:

If the request fails, a dialog appears with an error message that describes the cause of the fail.

Example:

Note: The manual Refresh Static APIs option applies only to static service APIs. Changes to the status of services that are onboarded to allow for dynamic discovery require a restart of the specific services where changes are applied. It is not necessary to restart the API Catalog or the Discovery Service.

Change password via API Catalog

In case expiration of a mainframe password, the API Catalog offers the possibility to set a new password, using either the SAF or the z/OSMF provider. For more information about the password change functionality, see Advanced Gateway features configuration.