Exposing partial API Documentation in the Zowe API Catalog
Segment your API into groups!
{Core} Some time ago, I was asked to help a customer to find a solution for how to expose just a segment of their API in Open Mainframe Project’s Zowe API Catalog. The customer is using combination of Java to build the API and SpringFox to generate the API documentation. His intent is to limit the exposed endpoints so that only the user facing endpoints are visible to API Catalog users, and hide the other (administrative) endpoints. I have created a small prototype and want to share it today.
You can find the full source code on GitHub.
API Documentation
SpringFox is a very clever library which allows you to generate an endpoint, that provides the API Documentation in several standard formats. This is the default path for Swagger 2:
/v2/api-docsAbove that there can be API groups defined that you can retrieve from this path:
/v2/api-docs?group=externalThis can be very conveniently used to generate the various API documentations we will need to accomplish the task.
As you can see in the sample, there are three endpoints: /admin /user and /greeting
The sample embeds SpringFox configuration which defines the basic API groups. There are plenty of other ways how you can segment the API and define that segmentation in your application with SpringFox, but for the sake of demonstration, the simplest approach is used. Notice that there is a default API that captures all endpoints. This can be used when segmentation is not required.
Now that the API documentation is prepared and segmented, we can create the rest of the use case.
Zowe API Mediation Layer registration
The sample uses Zowe’s API Mediation Layer’s Plain Java Enabler library to onboard into Zowe. It is configured such that when started, it will onboard into a local instance of API Mediation Layer (clone the repo, follow the quick start documentation, start the instance). The magic is in the metadata that the sample registers into the Zowe Discovery service.
The sample code needs to dynamically configure this property config.getApinfo().get(0).setSwaggerUrl(apiDocUrl)to register the correct swagger documentation URL. http://localhost:8080/v2/api-docs?group=publicapi is used for a public API, http://localhost:8080/v2/api-docs?group=adminapi is used for a admin API. You get the idea.
The sample makes use of Spring profiles functionality to decide which API segment to expose at startup and then injects the configured value into the ApiMediationServiceConfigobject. Again, there are multiple ways how to accomplish this, depending on your case. You can find the complete configuration and injected values in the source code on GitHub.
After the sample is started, it registers to Discovery service with the desired swagger documentation URL, which will be in turn loaded to the API Catalog and displayed. The outcome is a single API service which can decide dynamically, without any code change, which segment of API will be exposed. It just needs to be built in this particular way. The displayed API documentation will not prevent clients from calling the “hidden” APIs. If you wish to limit accessibility, you need to take further steps on the service’s side, securing or even disabling the endpoints.
I hope you find this sample helpful!
Finding out more
If you enjoyed this blog, checkout my other blog about Zowe Client Certificate Authentication, or 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.
Zowe is an open source project and all of the code is available at https://github.com/zowe.
