Introducing “Try it out” functionality in the Zowe API Mediation Layer

{Core} As a system administrator of the Open Mainframe Project Zowe API Mediation Layer, managing the massive ecosystem of Zowe can become a real challenge. Infact as the vision for making mainframe technology more accessible to a broader audience is quickly becoming reality through Zowe, an increasing number of services are being made available every day. An exciting new feature in Zowe’s API Mediation Layer makes it easier than ever for developers to validate that services are giving them the responses they expect. This new feature, which has just been introduced to the API Mediation Layer component is the “Try it out” functionality.

The API Mediation Layer is built on three core services: the Discovery Service, the Gateway, and the API Catalog. Together, these services provide users with a single point of access to mainframe service REST APIs. The API Catalog serves as a user-friendly UI where users can see all discovered microservices that have been integrated or “onboarded” with the API Mediation Layer, as well as view their associated APIs, and Swagger documentation.

The role of the API Mediation Layer

You are a modern system administrator responsible for managing the availability and operation of services (APIs) for products, subsystems and tools in your z/OS environment. You also develop scripts and dashboards that consume those same services.

Without a single place where you can easily find and test mainframe APIs, managing all of these tasks simultaneously can be pretty daunting, and may make your job more complicated than it needs to be. This is where the API Mediation Layer (API ML) comes in. The API ML functions as a modern, light-weight interface with a single sign-on feature which enables you to directly access the entire ecosystem of Zowe REST APIs, while also enabling you to create, build, manage, and operate Z systems and resources.

The API Catalog as an API testing tool

Once you’ve discovered how the API ML can help simplify your workflow, and have “onboarded” a service to the API ML, you probably want to verify that the service and its APIs are working as they should.

Until now, the API Catalog component of the API ML was able to display API documentation, but it was not actually possible to test them. From the user perspective, this posed a problem as validation was only possible by means of either an external API client, such as Postman, or a command-line tool like cURL.

With the newly released “Try it out” functionality, it is now possible to access the API Catalog and simply try out a service’s REST API endpoints by defining the parameters (if present) in the request, and then executing the request to receive the actual response — all of this made possible by the API Mediation Layer!

Authorize your endpoints

There are two types of endpoints which can be defined in the API Catalog:

• public endpoints, which are accessible without entering user credentials.
• protected endpoints, which are only accessible by entering user credentials. These endpoints are marked with a lock icon.

When you use the “Try It out” functionality to test a protected endpoint, you’ll see a lock icon and when you click that icon you’ll see a dialog like the one shown here. As part of the “Try it out” functionality, a developer who has onboarded a service can protect specific endpoints by requiring authorization whenever an end-user would like to send a request to a specific resource. This is done by defining the HTTP authorization scheme supported by Swagger UI, which enables endpoint protection through Basic Authorization.

Authorization dialog that appears once the user clicks on the lock icon

Time to try it out!

Let’s walk through the process to try out a protected endpoint.

First, let’s deploy the API Mediation Layer. Here is a useful blog which describes how to run all the API ML components locally and how to onboard your service.

Once the API Mediation Layer is up and running, here’s the process to try out a protected endpoint.

1. Navigate to the API Catalog URL available at https://<mainframehost>:<gateway_port>/ui/v1/apicatalog .
2. Login into it by using your z/OS credentials.
3. Navigate to the detail page where the Swagger documentation of your service is displayed by clicking on the related tile.
4. Expand one of the protected endpoints. (In this case we are taking POST as an example).
5. Click on the lock icon and insert the required information in the Authorization dialog
6. Once you have authorized the protected endpoint, click Try it out. Once you click it, the example value in the Request Body field becomes editable.
7. 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.
8. Finally, click Execute.

As a result, the API Catalog Swagger UI submits the request and shows the curl command that was submitted. The Responses section shows the response.

Here is an example of the Try it out functionality for a public endpoint

In addition to accessing and modifying resources, you can now also test that the APIs and REST services are working as they should without using an external API testing tool.

Summary

Thanks to the “Try it out” functionality, the API Mediation Layer now offers a more user-friendly experience, which allows developers to not only visualize but also interact with the API’s resources, without having to use an external API testing tool. Additionally, the consumed API resources can now be protected thanks to the authorization. As Zowe is open source, we very much welcome your feedback, so feel free to let us know what you think of this new “Try it out” functionality.

Zowe is owned and managed by the Open Mainframe Project that is a Linux Foundation project.

If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the OMP slack channel register here.