We at the Broadcom Mainframe Division continue to invest in building APIs so that we can extend the usability of our products and thus deliver more value to our customers. The Broadcom Techdocs organization supports this API investment by adding modern, consistent, and intuitive API content to ensure that users have an efficient and productive experience.
So, let’s dive right in and explain what we’ve been up to.
Improved REST API Documentation
Whether your job is to configure a REST API server, set up REST API security, or you use product endpoints in your day-to-day job, we want to make it easy for you to find the information you need and use that information as efficiently as possible.
By working closely with our users, we’ve identified some common areas to target for improvement and/or consistency across all mainframe product API documentation. These include:
-
Architecture and Flow Diagrams
-
Standardization Across Products
-
More information on Zowe integrations
-
Modernized Use the REST API Article
-
Verification Steps
-
More Examples
Now, let’s expand on each of these points, why we focused on that particular point, and how these enhancements help you.
Architectural and workflow diagrams
Why? To quickly understand the product API structure and configuration scope
No matter your job role, understanding how all the pieces fit together in the product’s API architecture will help you to perform your job more efficiently now and in the future.
All Broadcom mainframe products that offer an API either have or will include an architecture diagram like this one in the documentation (taken from the ESP Workload Automation product documentation):
Seeing an architecture diagram might be more helpful than just reading a description of the architecture.
The same goes for when you try to configure a REST API server. So, our API documentation includes an intentionally simple flowchart of the steps required to configure your product’s API.
Being prepared up-front with an idea of the configuration process and what is involved will help you to plan and execute the configuration more efficiently.
Here is an example of one such REST API configuration flowchart from the OPS/MVS Event Management and Automation documentation.
Standardized API Documentation Across Products
Why? To enjoy a consistent, high-quality documentation experience across products
If you’re a Broadcom customer, chances are that you’re using multiple Broadcom mainframe products. It may even be that you yourself have configured or at least work with a number of Broadcom mainframe products.
Our customers have told us that they want our documentation to look the same or similar across products.
You talk. We listen.
The same goes for our API documentation.
We’re in the process of standardizing our REST API configuration pages, requirements pages, using pages, and Zowe integration pages. So that no matter which product’s API information you need, you’ll be able to go to that product’s API documentation and know exactly where to look and what to look for.
Here you can see a couple of Configure the REST API pages for two different products. Different products, yet the same or similar titles, sections, style, and structure- all for a better customer documentation experience:
More Info on Zowe Integrations
Why? To ensure that you can easily integrate with Zowe components
As the benefits of integrating mainframe products with Zowe become clearer, you had better believe that we want to make our products’ integrations easier and more straightforward.
As part of our REST API improvement efforts, we’re standardizing our Zowe integration documentation. So, if the Broadcom product that you use is required or recommended to integrate with Zowe, then you’ll find all the information you need to perform that integration in a less burdensome way.
Whether you’re interested in (or required) to integrate with Zowe API Mediation Layer, Zowe CLI, or you have another kind of Zowe integration to do, our documentation will have what you need to get the job done.
Modernized Use the REST API Article
Why? So you know exactly how to use the product APIs to accomplish your goals
If you’re an application developer, you’ll want to read this one. We’re placing a hefty focus on adding the modern, standardized, and intuitive using the REST API information you need to build your applications and interact with our product APIs to accomplish your specific business tasks.
With standardized sections across products, you’ll know exactly where to look for information on: sample use cases, prerequisites, authorization and authentication requirements, URL structure, troubleshooting, and of course, the Swagger specification for each API endpoint.
Verification Steps
Why? To ensure that you set things up successfully
When you configure something, you would probably prefer to know that your configuration was successful instead of just guessing that you were successful. We get that.
An important focus for our REST API documentation improvement effort is making sure that our product documentation includes clear verification steps. This is especially the case when it comes to configuring REST API servers.
More Examples
Why? To build confidence that you’re accomplishing your job task correctly
Speaking of examples, we’re giving you more examples.
Examples are a great way to help ensure that you’re doing something correctly. We want to give you that confidence by providing you with more API documentation examples.
For example, take a look at this Use the REST API page from the Mainframe Application Tuner product documentation:
Check Out Our Modern Mainframe REST API Docs
From simplifying REST API configuration tasks to streamlining Zowe component integration to enhancing intuitiveness through helpful diagrams, verification sections, and examples, our API doc modernization efforts help you to get stuff done in an easier way.
Our current REST API documentation enhancement effort is not the end! We never stop looking for ways to help our customers work with our mainframe products in an easier, more efficient, and ultimately better way.
For any questions or comments, please write to us at techpubs.feedback@broadcom.com.