The YAML Onboarding Wizard: an easy way to onboard your REST API service to the Zowe API Mediation Layer
{Core} With the Open Mainframe Project Zowe steadily gaining greater recognition and seeing a continuous increase in its usage, there has been no shortage of opportunities for the Zowe community to learn from its early adopters. One of the things we noticed is that the onboarding process for new REST API services to the Zowe API Mediation Layer (API ML) sometimes required assistance or support, especially for those unfamiliar with the API ML and the Zowe ecosystem. Clearly the goal is to make the onboarding process so easy that the typical experience is free of frustrating delays, and as the number of users adopting the API ML has increased, the Zowe development teams realized the urgency for enhancing the overall user experience.
One recent enhancement that has taken the Zowe user experience to a whole new level is the development of a new YAML Onboarding Wizard, available since version 1.25. This Wizard provides a user-friendly interface that walks the onboarder through all of the steps necessary to create a correct configuration file which is then used to set the application properties and the Eureka metadata. Previously, the onboarding process might take several hours to customize all of the configuration parameters. Using the Wizard, onboarding an API can be accomplished in a couple of minutes.
Let us start off by looking at a possible use case of an API developer who would like onboard a REST API by utilizing this new API ML Wizard. As an API developer, let us say you have your REST API service that you would like to make Zowe-conformant, and in order to do that you have to onboard your service to the API ML. By using the YAML Onboarding Wizard, a UI component of the API Catalog, you can now streamline the onboarding process and mitigate issues that might result from misconfiguration, or a general lack of API ML familiarity, before these issues arise.
The supported onboarding methods
If you are not yet familiar with the Zowe API Mediation Layer, you may first want to check out this blog which provides a clear overview of the API ML. Another resource worth checking out is the Onboarding Overview article on the Zowe Docs website, which describes the various ways to onboard your service to the API Mediation Layer.
Assuming you are already familiar with the Zowe API ML, and understand that APIs can be onboarded to show their availability in the API ML either statically, or dynamically, you will be glad to hear that the Wizard supports both of these onboarding methods (called enablers), which integrate your REST API service to the API ML.
The specific onboarding enablers you use to onboard a REST API to the API ML depends on the programming language or framework used to build your REST service. The dynamic onboarding enablers are:
- Onboard a REST API service with the Plain Java Enabler (PJE)
- Onboard a Spring Boot based REST API Service
- Onboard a Micronaut based REST API service
- Onboard a Node.js based REST API Service
The static onboarding methods, in case your service is not built with Java, or you do not want to change your codebase or use the previously mentioned libraries, are:
- Onboard a REST API using static definition without code changes
- Onboard a REST API directly calling Zowe Discovery Service
When using the Wizard, you can specify one of the onboarding methods described above, depending on your needs.
Onboarding your REST service with the Wizard
Now, let us take a look at how you can use the Onboarding Wizard within the API Catalog. Here is how you do it:
- In the dashboard of the API Catalog, click the Onboard New API dropdown located in the navbar.
2. Choose the type of onboarding according to your preference (static or via enablers).
3. Fill in the input fields according to your service specifications.
4. Address each of the categories in the dialog dropdown.
Let us take a look at how the wizard walks you through onboarding an API using the Plain Java Enabler. This is the point where you can populate the fields with the relevant API information.
5. Click Save to apply your changes.
6. Validate successful onboarding with the following step according to your onboarding method.
In the case of static onboarding, you can validate the onboarding process by clicking Refresh Static APIs.
For static onboarding, a validation message appears after successful onboarding.
For onboarding using an enabler, click Copy to save the generated yaml file to your clipboard. Then paste this yaml file in your project’s service-configuration.yml file.
7. Finally, check the API Catalog. If your service is in the list of available services, your API has been successfully onboarded.
Wizard as a configuration validator
The Onboarding Wizard also helps identify the mandatory configuration properties to help the user understand the correct values for these properties. Here is an example:
API ML dev teams are continuing to look at how to best assist developers to increase developer awareness of the API ML ecosystem by providing even more tips in subsequent releases of the Wizard.
Conclusion
To support the main principle of the Zowe conformance program, and to improve the process of integrating REST API services to the Zowe ecosystem, the YAML Onboarding Wizard aims to facilitate the work of the API developer by providing an intuitive and user-friendly way to onboard a REST API service to the Zowe API Mediation Layer.
Special thanks to Diana and Viktor Korladinov for their valuable contribution during the development of the YAML Onboarding Wizard.
If you enjoyed this blog, and would like to learn more about Zowe, check out more Zowe blogs here. You are also welcome to 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.