Digital Developer Conference: Cloud Security 2021 – Build the skills to secure your cloud and data Register free

Generate client code for service APIs using open source tools

As developers, we always like using APIs that have a familar look and feel. It means we can interface with a service without trudging through documentation! An added bonus is client code in a language of our choice.

The OpenAPI Specification (OAS) is a community-driven open specification within the Open API Initiative, a Linux Foundation Collaborative Project. The OAS defines a standard, programming language-agnostic interface description for REST APIs.

Services on the IBM Cloud are or are now in the process of providing OpenAPI Specifications for their APIs. This is very beneficial to the developer as there are a number of tools available which generate client code in a number of languages using the specification. It essentially means client code in a language the way you like it, for a service you want to use.

Learning objectives

After completing this guide, you will know how to:

  • Understand what the OpenAPI Specification is.
  • Generate client code for service APIs using SWAGGERhub.
  • Connect to an IBM Cloud Container Service API using generated client code.

Prerequisites

To follow this How-to guide, you need to have:

Estimated time

To complete the how-to should take about forty minutes. Twenty minutes for the prerequisites and another twenty minutes for the guide.

Steps

In this guide, we will use the IBM Cloud Container Service to demonstrate.

Retrieve the Container Service OpenAPI specification

  1. Download the Container Service OpenAPI specification.
  2. Change the specification to be HTTPS only:
 "schemes": [
    "https"
  ],
  1. Change the specification host to the region of the container service. For example, for US South region:
"host": "us-south.containers.bluemix.net"

Generate Container Service client code

  1. Use your tool of choice to generate the client code from the OpenAPI specification. In this case we are using SWAGGERhub to generate the code.

  2. Select Import and Document API.

    SWAGGERhub Import

  3. Browse to the location of the updated Container Service OpenAPI specificationand click Upload File. Specification should be loaded as follows:

    SWAGGERhub API View

  4. Generate client code as per your language of choice. We will generate JavaScript as follows:

    Generate Client Code

  5. The code will be made avaiable to download as a zip file once generation is complete.

Connect to the Container Service using the generated client code

  1. Extract the client code zip to a directory.

  2. JavaScript client code generated with Swagger uses import/export functionality and it is not supported in NodeJS yet (could be by the time you read this!). We therefore suggest transforming the client code to ES5 using a tool like Babel.

  3. Write some test code using the generated client code to call a Container Service API. In this case we are using some simple NodeJS code to call the GET /clusters API:

var IbmCloudContainerServiceApi = require('<path-to-extracted-client-code>')

var clusters = new IbmCloudContainerServiceApi.ClustersApi()

var authorization = "<IAM Authorization Token>" // Run: bx iam oauth-tokens

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully.');
    console.log('Data: ', data);
  }
};
clusters.getClusters(authorization, callback);

Note: The Container Service uses IBM Identity and Access Management (IAM) to enable secure access to its APIs. To retrieve an authorization token for an API call, you need to run this IBM Cloud CLI command bx iam oauth-tokens. When you use the token, remove Bearer from the value of the token that you pass in the API call as shown in the code above.

Summary

We hope that this shows how easy it can be to generate client code in a language of your choosing, when a service defines an OpenAPI Specification. In this guide we used the IBM Cloud Container Service to demonstrate but this should work for any service with an OpenAPI Specification.