Contents


Make the most of container technology with the IBM Bluemix Container Service API

Create cool apps using the API for this Docker-based service

Comments

As containers play an increasingly prominent role in information technology, Docker continues to grow in importance. More and more, IT design teams are looking to Docker as the basis for their architecture. To keep pace with this container movement, IBM has released its own Docker-based container solution, the IBM Bluemix Container Service.

With the API, you have the ability to interact easily with the Bluemix Container Service. Because you are not blocked by the tools, you are free to imagine any number of cool applications that you can develop using this API.

To interact with the service, you can use the Bluemix console or the command line (cf), as you would with Cloud Foundry Services. But what happens if you have more specific needs? How could you integrate the management of your container instances, deployed on Bluemix, inside a custom or third-party application?

One option would be to use the API. In the same way that, on Bluemix, you can use the Cloud Foundry API to interact with Cloud Foundry applications and services, you can interact with the Bluemix Container Service by using its API. In this tutorial, I explain how to use the Bluemix Container Service API to address these requirements.

Figure 1. Ways to interact with Bluemix Container Service
Chart showing ways to interact with Container Service
Chart showing ways to interact with Container Service

Step 1. Discover the API of the IBM Bluemix Container Service

The API is documented at IBM Containers API. This page describes the different API operations that a developer could use in an application to interact with container services (container, volumes, registry, and so on) on Bluemix. For each API, the documentation includes information about the operations. It describes each operation by providing:

  • A brief introduction to the operation's purpose
  • The structure of the response, if the call succeeds (status code 200)
  • The list of input parameters and their attributes
  • The error response messages, including the status code (other than 200) and the associated reason
Figure 2. Descriptions of API operations
Screen capture showing how API operations are described
Screen capture showing how API operations are described

With this information, it's easy to code an application to do a REST API call.

Step 2. Understand the REST API call and the required authorization parameters

Before jumping into programming, you should understand how the authorization information is retrieved and used during the API REST call.

Most Bluemix Container Service API operations require an X-Auth-Token and an X-Auth-Project-Id as parameters. These must be passed into the header of the request. X-Auth-Token is a JSON web token (JWT) that you receive when you log into the Bluemix platform. You should use it to allow your API call to interact with the container service. To retrieve the token, use the following cf command.

cf oauth—token

Figure 3 shows the result:

Figure 3. Result of cf oauth—token command
Screen capture showing result of cf oauth—token command
Screen capture showing result of cf oauth—token command

Similarly, you need the X-Auth-Project-Id—the unique ID of your organization space where you create and work with the container. You can retrieve this ID by using the following cf command.

cf space container ——guid

Figure 4 shows the result:

Figure 4. Command result
Screen capture showing command result
Screen capture showing command result

You could easily check the validity of these two results by issuing a curl command, which does a call to a URL. Here, you will use it to invoke a Bluemix Container Service API. The syntax of that command is:

Listing 1. Curl command invoking API
Curl –X GET --header "Accept: application/json" --header "X-Auth-Token: your-auth-token" --header "X-Auth-Project-Id: your-project-Idthe-target-API-endpoint"

In the Listing 2, your-auth-token is replaced with a valid X-Auth-token, your-project-Id with a valid X-Auth-Project-Id, and the-target-API-endpoint with https://containers-api.ng.bluemix.net/v3/images/json.

Listing 2. Updated curl command
curl —X GET ——header "Accept: application/json" ——header "X—Auth—T0ken: eyJhbGci0iJIUzI1NiJ9.eyJqdGki0iI0ZTc3MzAxYy1kYjhmLTRlYm01tYjhj0C01YjMxMTc0YzEzZWUiLCJzdWIi0iIxYmE10WY3ZCOzMTBiLT01M2MtYjk0ZS04ZTMzYzk1ZDZiZGOiLCJzY29wZSI6WyJjbG91ZF9jb250cm9sbGVyLnJIYWOiLCJwYXNzd29yZC53cml0ZSIIsImNsb3VkX2NvbnRyb2xsZXIud3JpdGUiLCJvcGVuaW0iLCJ1YWEudXNlciJdLCJjbGllbnRfaW0i0iJjZiIsImNpZCI6ImNmIiwiYXpwIj0iY2YiLCJncmFudF90eXBlIj0icGFzc3dvcm0iLCJ1c2V5yX2lkIj0iMWJhNT1mN20tMzEwYi00NTNjLWI5NGUt0GUzM2M5NW02YmRkIiwib3JpZ21uIj0idWFhIiwidXNlcl9uYW1lIj0iamVyb21lLnRhcnRl0GZyLmlibS5jb20iLCJlbWFpbCI6Implcm9tZS5j0YXJOZUBmci5pYm0uY29tIiwicmV2X3NpZyI6Ij1mZGUwMzRmIiwiawFOIj0xNDg1Nzg5MjU1LCJ1eHAi0jEO0DY50Tg4NTUsIm12cyI6Imh0dHBz0i8vdwFhLm5nLmJsdwVtaXgubmVOL29hdXROL3Rn1va2VuIiwiemlkIj0idWFhIiwiYXVkIjpbImNsb3VkX2NvbnRyb2xsZXIiLCJwYXNzd29yZCIsImNmIiwidWFhIiwib3BlbmlkIl19.cmcVjYuEKhjH5xFxJA5bFVK9xzzbLud7PVzbdcb3eR0" ——heaider "X—Auth—Pr0ject—Id: e9495a40—2dff—4a42—beac—22f63cc328c0" "https://containers—api.ng.bluemix.net/v3/images/json"

Figure 5 shows the result:

Figure 5. Curl command and results
Screen capture showing curl command and results
Screen capture showing curl command and results

The code and figure show the result of a call to get the image list. The call retrieves the list of available images in your private registry, hosted in the Bluemix Container Service.

Step 3. Include the REST API call in a sample application

From the previous section, you should understand the Bluemix Container Service API and how to pass authorization to it. You can now include it in your application, using your preferred programming language (Java, JavaScript, Swift, and so on). The call to the API is a REST call.

Next, I'll use a sample application to show you how to do this using nodejs/express and the unirest package.

Figure 6. Sample application accessing Bluemix Container Service
Chart showing sample application accessing Bluemix Container Service
Chart showing sample application accessing Bluemix Container Service

Listing 3 shows the REST API call to retrieve the list of existing images in the private registry (just as the curl call did in the previous section):

Listing 3. REST API call to get list of images in registry
/* ----------------------------------------------------------------------------------------------*/
/* Call the REST API to get the list of existing images managed by Bluemix Container Service    */
/* ----------------------------------------------------------------------------------------------*/
app.get('/images', function(req, res){
    console.log("Call the rest API to get images list")
    var cred = getCredential(req);
    unirest.get("https://containers-api.ng.bluemix.net/v3/images/json")
    .header("X-Auth-Token",cred.token)
    .header("X-Auth-Project-Id",cred.project)
    .header("Accept", "application/json")
    .end(function (result) {
      res.render("home/images",{code: result.code, result:result.body});
    }
    )
});

In the sample application, the X-Auth-Token and X-Auth-Project-Id credentials are stored in the session. A page of the sample application provides a form for entering the two necessary values. By storing the credentials in the session, you can share the same credentials across the different calls that the application might make.

(Of course, you can manage the user identification and authorization by using OAuth API. By calling the /oauth/token API of the Bluemix authorization endpoint (https://login.ng.bluemix.net/UAALoginServerWAR ), you then proceed to your user login and enter your Bluemix id and password. The API call response will then return the authorization token. This mechanism is not implemented in the sample application.)

By calling the getCredentials function, the application retrieves the X-Auth-Token and X-Auth-Project-Id values from the session and allows them to pass into the REST API call.

The unirest object does the REST API call. By using the get method, the code indicates that the call should invoke the get operation of the targeted API. Its endpoint is provided as input for the get method. The call of the header method allows you to provide header information for the call. In the sample, this method provides the mandatory authorization information. Ultimately, a call to the API is done by invoking the end method.

You use the callback function to call the rendering of the response page. In this sample, the rendering is done by the /home/images page, which corresponds to the images.ejs file. The application uses the EJS template to render the page. The result of the API call is split into two variables, which are passed as parameters of the rendering function.

The page checks the code to verify that the REST API call has been made without error. In the case where the response code (passed in code) is not 200, the application gets an error and the page displays an error message, which includes the reason for the error. For more information about the possible error, you should consult the API documentation.

Otherwise, all is well. The page displays the result. The images.ejs page does a loop on the result variable. It contains the result.body of the REST API call response, and for each iteration, it displays the characteristics of the image.

Listing 4. REST API call response
<!doctype html>
<html>
  <head>
    <title>
      ICS Images
    </title>
    <link rel="stylesheet" type="text/css" href="collapse.css">
  <body>
    <%- include("header");%>
    <H1> Images</H1>
    <%- include("error");%>
    <% for(i=0;i<result.length;i++) { %>
      <div class="row">
        <a href="#hide<%= i %>" class="hide" id="hide<%= i %>"><%= result[i].Image %></a>
        <a href="#show<%= i %>" class="show" id="show<%= i %>"><%= result[i].Image %></a>
        <div class="list">
          <P> ID: <%=result[i].Id %></P>
          <P> Tags: <%=result[i].RepoTags %></P>
          <P> Size: <%=result[i].Size %></P>
          <P> Virtual size: <%=result[i].VirtualSize %></P>
          <P> Created: <%=result[i].Created %></P>
        </div>
      </div>
      <br>
    <% } %>
  </body>

Figure 7 shows the result of the call done by the application:

Figure 7. Result of call done by application
Screen capture showing result of call done by application
Screen capture showing result of call done by application

You can clone the sample application used in this article from a Git repository at https://github.com/jtarte/ics-remote-manager

Conclusion

As this sample application shows, it is easy to develop an application that interacts with the Bluemix Container Service. Still, the question might arise: Why do you need to call an API to interact with your container resources deployed in Bluemix? You have the ability to administer your containers by using the Bluemix web console or by using the Bluemix command line, so you won't usually need to do a REST API call. In some cases, however, you might find it helpful to be able to manage your container resources this way.

For example, imagine you need to get a global view of your resources on Bluemix. When you work with the Bluemix console or command line, you are working in a single Bluemix space. If you want to get a view of all your container resources, you must swap between the spaces to get the information for each.

Figure 8. API interacting with multiple Bluemix spaces
Chart showing API interacting with multiple Bluemix spaces
Chart showing API interacting with multiple Bluemix spaces

By using the API, you can build an application that will chain the calls for each space and consolidate the result into a single view. You can develop a management application that provides a global view of your container resources on the Bluemix Container Service.

API calls can also be useful for IT service management. The containers you deploy on Bluemix are part of your IT systems, so you probably want to manage them in the same way that you manage other resources. If you're using a central IT service management tool, you want to be able to use it to manage your container resources deployed on Bluemix.

Figure 9. Service management tool using API to access Container Service
Chart showing service management tool using API to access Container Service
Chart showing service management tool using API to access Container Service

By interacting with the Bluemix Container Service through API calls, you can facilitate the integration into your IT service management tool.

You can probably imagine other such cases, depending on your requirements. With the API, you have the ability to interact easily with the Bluemix Container Service. And because you are not hindered by the tools, you are free to come up with any number of cool applications that you can develop using this API.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing
ArticleID=1045255
ArticleTitle=Make the most of container technology with the IBM Bluemix Container Service API
publish-date=05092017