How the Zowe API Gateway consolidates, aggregates, manages and publishes z/OS services

The API Gateway is the single point of access which then directs the requests to proper services

{Core} The API Mediation Layer feature of the Zowe — Open Mainframe Project is comprised of three principle components: The API Discovery Service, the API Catalog, and the API Gateway, which together provide clients with easy access to registered mainframe REST API services. This blog post takes a deeper look at the roll and versatility of gateways, why they are increasingly important in enterprise service provision, and how to onboard new services to the Zowe API Mediation Layer through the Gateway using a local Docker image. Additionally, this post addresses the question of how to contribute to the API Gateway itself using github forks and pull requests.

For at least a decade now, most application services have been built with developer usability in mind, by exposing one or more APIs that can then be readily used across the API development community. In the enterprise environment that leverages mainframe technology, however, these application services have been limited to those inside a given organization, whereby APIs have only been accessible via local networks or through VPN.

Pressure from external stakeholders, as well as demands in the market, have demonstrated the clear need for broadening access to mainframe-based application services outside of an isolated organization. In the world of banking, the PSD-2 directive by the European Union is a clear case of this technological demand.

Broadening service accessibility, however, reveals numerous relevant concerns which are shared across the global development community, such as:

• How do we give the user access to specific services without granting access to the internal network?
• How can services be properly secured and still enable a single sign-on experience for all internal services?
• How can multiple deployed services be provided simultaneously?

A gateway preventing intruders from getting in by Bart Everson

The solution developed within the Open Mainframe Project’s Zowe is to deploy a gateway application, which operates as a border to the organization. The gateway is a single point of access that properly routes requests to internal services while making sure that the users are authenticated before getting access. Additionally, this gateway ensures that the load on the internal applications does not overwhelm users with a flood of requests.

Zowe and its role

A gateway application, with such features, has been packaged as a part of the Zowe — Open Mainframe Project. A standard Zowe installation deploys this gateway to your system, making it ready to use off the shelf. The application is developed as a service included in the API Mediation Layer.

• The API Mediation Layer allows you to use and build upon the internal SSO capabilities.
• The API Mediation Layer manages proper routing to the internal services without consumers needing to know anything about the internal network.
• The API Mediation Layer automatically handles load balancing and makes sure that as long as at least one of the instances of the service is up, the request will be properly handled.

More information about the role and usage of the gateway to provide security is found in this article.

Run the API Gateway locally

The Zowe API Gateway is available as a standalone solution packaged in a Docker container for local deployment. The aim of this standalone offering is to enable a service developer to verify the onboarding of service to the API Mediation Layer in the local environment with only minimal configuration.

To try it out, you first need to download and install Docker. Due to constraints on the Docker networking model in Windows and Mac environments, the guideline is currently only applicable for Linux hosts.

After you have Docker installed, open in a command shell, and run following commands:

docker run --rm --name api-layer --net host -d jbalhar/api-layer-development:1.0.2 /sbin/my_init
docker exec api-layer bash _run

These two commands run and start the whole Zowe API Gateway. In the image below you see the pieces from the process of updating to the latest version, building and deploying all the components of the API Gateway.

Here’s an example run of the whole procedure.

All the services are started and ready when the following lines are displayed:

[DS] 2020–04–07 14:28:22.969 <ZWEADS1:main:1493> root INFO (o.z.a.p.s.ServiceStartupEventHandler) ZWEAM000I Discovery Service has been started in 51.981 seconds
[GS] 2020–04–07 14:28:26.764 <ZWEAGW1:main:1487> root INFO (o.z.a.p.s.ServiceStartupEventHandler) ZWEAM000I Gateway Service has been started in 55.869 seconds
[AC] 2020–04–07 14:28:27.030 <ZWEAAC1:main:1486> root INFO (o.z.a.p.s.ServiceStartupEventHandler) ZWEAM000I API Catalog Service has been started in 56.101 seconds

At this point, you should be able to access the Gateway, Discovery Service, and API Catalog.

• The Gateway is available at https://localhost:10010
• The Discovery Service is available at https://localhost:10011. This service serves as a repository for all current services that have onboarded to the API Mediation Layer and checks for the status and availability of the onboarded service.
• The API Catalog is accessible via the Gateway and serves as a UI for exploring all available APIs and their associated documentation.

Onboarding my service

Once you’ve run the API Gateway locally, the next step is to onboard the service. There are two ways you can onboard a service:

• Integrate the library for Plain Java and Spring Boot applications
• Onboard the service statically by providing a specific yaml based configuration to the Gateway.

Documentation about the different ways to onboard your service to the API Mediation Layer is found in the Onboarding Overview article on the Zowe Docs website.

Note that if you are onboarding the service via static onboarding, the default directory for the configurations is /var/src/api-layer/config/local/api-defs.

Change the API Gateway

While working with the API Gateway, you may have encountered something that you dislike or something that can be done better. As the API Gateway is Open Source, you are welcome to help us make improvements with your suggestions and input.

Here’s the general process to follow to contribute:

1. Fork the original (api-layer) repository (https://github.com/zowe/api-layer)
2. Clone the fork
3. Create a branch to make changes in it
4. Verify that it builds and that the tests are passing
5. Push the branch to your fork
6. Create a new Pull Request to the original repository

The Docker container includes all the tools you need to verify whether the changes you propose work.

You may be wondering, how can this container simplify my work?

Here’s how:

• The container contains the original repository configured to use the master branch ready in the /var/src/api-layer. To use the fork for the build and testing you only need to change the remote URL to your fork.
• The whole build and testing procedures necessary to properly pass through the Pull request tests are run by the _test script.

Here’s an example of a test run.

Summary

Using the Docker container with the API Gateway simplifies the process of onboarding a REST API service to the API Mediation Layer and its micro-services. We look forward to your contributions and collaboration as we collectively advance this exciting technological frontier.

Click the links to learn more about Zowe and more Zowe blogs.