Zowe Enhances the API Consumer Experience with Code Snippets

{Core} The recent release of Open Mainframe Project’s Zowe V2 has opened the door to an even more user-friendly way for developers to leverage APIs onboarded to the API Mediation Layer (API ML). New features that significantly improve the developer experience have been added by providing functionalities that enable direct integration of APIs into new applications.

Along with the significant growth in the adoption of the API ML and of services registered to it, it has become increasingly apparent that there is a need for a new approach to facilitate the API consumer to more readily incorporate and make use of service APIs exposed in the API Catalog. Generally speaking, there is a clear pattern showing that not only do API consumers want to interact with service APIs, but they also want to use these APIs in an application.

Applications, however, can be written in any number of languages, and implementing code to incorporate some service APIs into an application may be both intricate as well as time-consuming.

To mitigate this problem, Zowe has introduced a new capability, available with Zowe version 2.3, that allows the API Catalog to provide Code Snippets for APIs of services registered to the API ML. The aim is to demonstrate how an API consumer can invoke and effectively use a selected API operation.

By providing Code Snippets, the API consumer can work more productively, leveraging APIs across an organization with greater ease. This new Code Snippets functionality provides examples of how to use service APIs in a range of different programming languages.

But it is not only about the API Consumer…

Photo by Austin Distel on Unsplash

While the Code Snippets functionality is primarily intended for the API consumer — who can now quickly understand an API’s use case and decide whether to use it in his or her application — there is, in fact, another persona who can also directly benefit from this functionality.

The API producer is the other side of the coin. By providing better examples of how to use the SDKs, an API producer can improve the adoption of service APIs which are ultimately utilized by the API consumer . This improvement to API service adoption is possible by defining custom Code Snippets as part of the configuration used to onboard a service to the API ML. Custom Code Snippets can contain more complex solutions and can show the full use cases typically achieved by a specific API operation.

Thanks to this customization functionality, while API consumers can now more easily incorporate service APIs into their applications, drawing on several supported languages, API producers can improve their APIs’ documentation and facilitate an improved understanding and usage of these APIs.

Let’s take a closer look at both basic as well as customized Code Snippets made available in this new feature.

Basic Code Snippets

Basic Code Snippets are those which are automatically generated for each service API operation, as part of the Try it out execution. These snippets are supported by a range of programming languages, including the following:

• C
• C#
• Go
• Java
• JavaScript
• Node.js
• PHP
• Python
• cURL

Each of these languages supports a specific HTTP Snippet library (i.e. Java Unirest, Java okhttp etc.).

Here’s what the language selection feature looks like in the UI:

Basic Code Snippets in different languages

Customized Code Snippets

Photo by KOBU Agency on Unsplash

While Basic Code Snippets provide REST API call samples in multiple languages which bring some benefit to the API consumers who want to try an API as a first step, these Basic Code Snippets do not actually provide a real use case. To show an API consumer a real-life example of the applicability of the SDKs, the API producer can specify a customized snippet as part of the service configuration.

Here’s an example of specifying different customized snippets:

apiInfo:
  -   apiId: zowe.apiml.sampleservice.rest
      ...
      codeSnippet:
        - endpoint: /greeting
          language: java
          codeBlock: |
            String template = "Hello, %s!";
            String defaultValue = "world";
            Greeting greeting = new Greeting(new Date(),
            String.format(template, defaultValue));               
            System.out.println(greeting.getContent());
        - endpoint: /greeting
          language: javascript
          codeBlock: |
            var template = "Hello, %s!";             
            var defaultValue = "world";             
            var greeting = new Greeting(new Date(),
                           String.format(template, defaultValue));                               
            console.log(greeting.getContent());
        - endpoint: /test
          language: C++
          codeBlock: |
            std::cout << "Hello, this is a test!";  

As seen from this example, the new apiInfo.codeSnippet configuration specifies the Customized Code Snippet for a specific endpoint (API operation). Within this configuration block, you can specify multiple Code Snippets for any API operation provided by your service. Once the request using the Try it out functionality is executed, the snippet is then displayed in the API Catalog under the related operation. When specifying this configuration, you just need to provide the following parameters for each of the snippets:

• endpoint
  The endpoint that represents the API operation of the customized snippet. Note: The endpoint must match the operation path displayed in Swagger documentation.
• language
  The language of the snippet. It is meant for naming the tab title in the Code Snippets panel. Eventually, you can specify any language you want.
• codeBlock
  The content of the snippet to be displayed in the API Catalog.

The following UI illustration presents customized Code Snippets provided by the API producer:

Customized Code Snippets provided by the API producer

Generate the Code Snippets in the API Catalog

Now, let’s take a look at how you can generate and visualize the Code Snippets in the API Catalog for a specific API operation.

Here is how you do it:

1. Click Try it out and execute the request, as described in the previous section.
2. The API Catalog generates the Basic Code Snippets, shown under the Code Snippet tab. If the API provider has also defined the Customized Code Snippets, these snippets are displayed in the snippet bar under a title prefixed with Customized.
3. Copy the Code Snippet of the chosen API and use it in your application.

Demo of the Code Snippets functionality in the API Catalog

Conclusion

To streamline the process of integrating and consuming the service’s APIs, the Code Snippets functionality can facilitate and speed up the work of the API consumer by providing code samples in the most popular programming languages, which can subsequently be incorporated within an API consumer application without any additional work. Furthermore, the API producer can now provide a real usage of the service’s SDKs, thereby enriching the service’s Swagger documentation and easing the adoption of such APIs.

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 questions 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 Open Mainframe Project slack channel register here.