API Documentation - Improvements to Search and Try it out

[balhar-jakub]

The actual Use Case

I (as a modern developer) was assigned to the modernization task that focuses on automating the build, test, and deployment process of one of our business applications. The application is running in the zOS environment and consists of the combination of batch jobs written in COBOL, rest APIs written in Java, and application code integrating with the system in C and HLASM. To deliver the full functionality I need to retrieve the code to be built from one of the VCS systems in use within the enterprise. The code will then need to be compiled on the zOS platform and packaged and uploaded as a version to one of the artifactories that the enterprise operates. This whole process is happening within the dev environment. After the code for all the parts is packaged I need to deploy the code to the validation environment and run the integration and end 2 end test suite against the running instances and if all these tests pass, I am allowed to deploy the application in the production environment. It's possible that manual approval will be needed to actually deploy the version to the production environment. To deploy in the production environment I need to get the final version of the code into the environment and install the new version. There can be a requirement to do this only within a specific time frame if we don't have an approach for zero-downtime deployments. If there is such an approach then I need to integrate it with the tooling that handles the deployment process e.g. via red/black or blue/green deployment strategies.

As for my experience, I have been working within the zOS environment for a year or two. I have an idea of how the zOS behaves and what systems are available, but I am far from an expert, and for lots of work I depend on more senior zOS experts that understand the platform better and are more knowledgeable about the platform. My colleagues are nevertheless already overloaded with other work and as such, it takes a while before they are able to help me with my questions which delays the work on my side. I also don't want to bother them too much and the trial and error process of learning takes too long as there is just a limited amount of realistic information on how to resolve specific problems on the zOS platform.

What do I want from the API documentation as presented by the API ML?

• As a modern programmer, I expect to be able to find endpoints relevant to my request. E.g. I want to know what endpoint can provide details about datasets to me.
• As a modern programmer, When I have an endpoint I want to be able to verify that the documentation is valid and that it behaves as I would expect.
• As a modern programmer, I want to be able to directly integrate the endpoint in my application without having to write the code for interaction over the REST.
• As an API developer, I want to be able to let the users know that they are using a deprecated endpoint and should stop using it.

An important note is that we are still focusing on the infrastructure APIs so the APIs that are used to build, test, deploy and operate the business APIs and services. Therefore the users and stakeholders are mainly internal within the organizations.

Solution requirements

Within this epic, I would like to find a solution to resolve the mentioned problems. I envision a workflow that will guide the user to the search functionality, for the found endpoints would allow the user to test their behavior directly from the page and if they like what they see it would provide them with the code snippet for the language of their choice that they can directly use.

[balhar-jakub]

As a part of the story - explore what is the possibility to use and help with HATEOAS with respect to the API Documentation and figuring out what does a specific API provide.