Skill Level: Any Skill Level

The evolution in information technology has driven the need to have interconnected devices and such rapid growing digital ecosystem requires APIs to consume business functions.


Step # 1.    Install Node.js on Windows. Link to install - https://nodejs.org/en/?cm_mc_uid=82902636420014577166807&cm_mc_sid_50200000=1457716680

Step # 2.¬†¬†¬† Install IBM API Connect Developer Tool Kit: # npm install ‚Äďg apiconnect

 The following items are installed when you install the developer toolkit.

  • API Connect CLI
  • API Connect graphical visual editor
  • Local API Connect Micro-gateway
  • Loopback


  • The Developer Toolkit is installed locally and provides an offline development experience. It is used for configuring, securing, and testing APIs locally.
  • It is integrated with the LoopBack¬ģ Framework.


  1. Introduction

    The integration of Systems of Engagement (SOE – a digital system, such as social networking) with real-time Systems of Record (SOR – a data source such as database) is needed to enhance the collaboration of enterprises and customers. This seamless integration is achieved by leveraging Bluemix hybrid cloud that offers a comprehensive solution integrating APIs. The evolution in information technology has driven the need to have interconnected devices and such rapid growing digital ecosystem requires APIs to consume business functions. The IBM Bluemix hybrid cloud solutions offer flexibility to rapidly compose APIs that help drive business values to enterprises.

    IBM API Connect for Bluemix integrates IBM API Management and IBM StrongLoop into a single offering that provides a comprehensive solution to create, run, manage, and secure APIs to drive digital content. The built-in LoopBack framework allows Developers to implement APIs, test them locally, and publish them to Bluemix.

    In today’s world, the volume and variety of data workloads require systems that can scale to manage the required data integration and management. IBM POWER8-based systems can manage on-premises mission-critical applications and database and also improves the I/O and memory bandwidth making the integration between cloud and on-premises systems faster.

    We carried out a PoC with API Connect on Bluemix. This was to capture the considerations for creating and designing a consumable REST API that developers can use as a starting point. We deployed ‚ÄúBookstore‚ÄĚ ‚Äď A System of Record legacy application (includes WAS and MQ) on IBM Power based Systems. The Bookstore Application has the OLTP (Online Transaction Processing) functions that simulate customers browsing and buying books. The Bookstore that runs on IBM Power Systems hardware, runs on AIX.

    From the Bookstore web url, you can search / browse books by Title, Author, Catrgory or ISBN.


     This recipe explores how APIs are transforming enterprise & customer interaction with hybrid cloud solutions. The subsequent steps drives through the process of creating, exploring, managing and securing APIs.

  2. Create a Loopback Project

    # apic loopback

    Enter Application and Directory Name (for ease of understanding, I have chosen same names).


      Select empty-server and then the required dependencies are installed


    LoopBack installs dependencies from the public npm repository. It installs all the project dependencies, as specified in package.json in node_modules directory and might take some time.




  3. Login to API Designer

    ¬†Changed the directory to ‚ÄúBookstore‚ÄĚ (created in previous step) and run # apic edit


    This redirects to the browser: Login with Bluemix credentials (Register to Bluemix, if you don’t have an account). Then the API Designer opens in your default web browser, where you can see the API created. Here you can create Model and Data Source.



    РLoopback Model: It connects to backend systems such as databases via data sources that provide create, retrieve, update, and delete (CRUD) functions. 

    РData source: Data source are system of records such as databases. In our scenario, we have on-premise DB2 database. Data sources are backed by connectors that implement the data exchange logic using database drivers or other client APIs. Install the corresponding connector as a dependency of your app with npm

    РLoopback Connector:  LoopBack provides connectors for popular relational and NoSQL databases. When you attach a model to a data source backed by one of the database connectors, the model automatically acquires the create, retrieve, update, and delete methods from  PersistedModel.  The data access methods on a persisted model are exposed to REST by default.

  4. Add Data source to your Loopback project:

    • Name: Datasource_name
    • Connector: IBM DB2 Connector (in my scenario)
    • Dsn (Optional)
    • Host: database_host1
    • Port: 50000
    • User: user-1
    • Password: pswd-1
    • Database: browsedb
    • Schema(Optional)

    Note: You can click on Install Connector to add the dependency to package.json. To install the DB2 database connector: # npm install –save loopback-connector-db2 Or, from GUI, click on Install Connector.


    Click on Save and it would test the data source connection. It should show success.


    The tool updates the app’s OpenAPI (Swagger 2.0) definition file and the server/datasources.json file with settings for the new data source.

  5. Add Model to your Loopback project:

    Add Model Name (the model name must match the table name in the database, and is case sensitive) à Enter the Properties (all the attributes need to be defined as in the table, and must match in case) àConnect this Model to Data Source à Select Basic Model: PersistentModel and Keep it Publicà Finally SAVE the model created.


    Note:¬† When creating a new model for the DB2 connector, there is no ‚Äúdiscover‚ÄĚ option like there is for MySQL, so the models have to be generated manually. In our ‚ÄúBookstore‚ÄĚ database, the table ‚ÄúTITLE‚ÄĚ had the following attributes:

     db2xxxx@xxxxxxxx[/home/db2xxxx]> db2 describe table title0

                                    Data type                     Column

    Column name                     schema    Data type name      Length     Scale Nulls

    ——————————- ——— ——————- ———- —– ——————–

    ISBN                             SYSIBM    CHARACTER                  10         0 No

    TITLE                            SYSIBM    VARCHAR                    150         0 No

    CATEGORY1                   SYSIBM    VARCHAR                     50         0 No

    CATEGORY2                   SYSIBM    VARCHAR                     50         0 Yes

    AUTHOR_NAME               SYSIBM    VARCHAR                    120        0 Yes

    PUBLICATION_YEAR        SYSIBM    SMALLINT                     2          0 Yes

    PUBLISHER                     SYSIBM    VARCHAR                    100       0 Yes

    WHOLESALE_PRICE         SYSIBM    DECIMAL                      7          2 No

    RETAIL_PRICE                 SYSIBM    DECIMAL                      7         2 No

    LAST_TRANS_TIME          SYSIBM    DATE                           4         0 No

    SEQ_NUM                        SYSIBM    INTEGER                      4         0 No


    Add the above attributes as properties to the Model



  6. Define API Path & Parameters:

    An API definition is composed of paths, which are the route, through which users access REST APIs. By configuring the Path, you define how the API is exposed to your developers.

     Some of the HTTP Operations are defined below:


    A Path comprises an HTTP verb and a URL path that, when exposed, is combined with the base path of the API. Specify the Operation ID that performs operations and Add parameters to include in the Path and its operations.

    For example: TITLE.find is the operation ID which find the instance that matches the parameter ‚Äúfilter[limit]‚ÄĚ from the data source (on-premise database)


    Enter values for filter. For example: Specify Filter [limit]:5 and click ‚Äúcall operation‚ÄĚ. The API provides a response¬† in JSON format by retrieving five records as requested.


    Specify API Property: An API property is a variable in an API where its value depends upon the Catalog in which the API is staged or published. To set the API Property – You need to define your API by specifying API properties, including property name, value and the Catalog to which the property applies. In the Default Catalog’s Value field, specify the default property value and SAVE.


  7. Testing the REST API

    Test your REST API to ensure that it is defined and implemented correctly. To test the REST API, complete the following steps:
    a. In the test console at the bottom of the screen, click the Start the servers icon:


    b. Wait until the Running message is displayed:


    Depending on your project configuration and whether other processes are running, a different port number might be displayed.

    Note: If your Micro Gateway is already running, you must restart it before you can test your changes, by clicking the Restart the servers icon

    Click the Assemble tab. Click the Test icon . The test tool opensà In the Operation section, select the get /details operationà Click Invoke. The operation is called by the test tool. The response of your API is shown in the test tool.


    Note: API Connect includes a number of built-in policies that you can use to apply preconfigured policy statements to an operation to control an aspect of processing in the Gateway server when an API is invoked. Apply the Invoke policy to call another service from within your assembly. The policy can be used with JSON or XML data, and can be applied multiple times within your assembly.



  8. Steps to Publish

     After you create and test APIs, you publish one or more Products to expose an API on the Developer Portal. You include an API in a Plan, which is then contained in a Product.

     a. API Connect also contains a service portal to publish local API creation and testing along with on cloud and on premise staging of APIs. In an API Connect Designer, after you create an API (or a set of APIs), you create a Product. A Product will have a set of APIs and Plans into one offering that you can make available to developers. You make APIs available and accessible to developer to use, only by staging and publishing the product in the Bluemix Catalog and in Developer Portal by publishing a product.

    b.     To stage the product: In the navigation pane of the API Designer, Click Productsà select the required product (in case you have multiple ones)à click on Publish iconà Add and Manage Targetsàselect Bluemix targetà select Bluemix regionàselect Bluemix organizationà select the catalog à Click Nextà Add a name to your application à Click Save


    c.      Click Publish again. Select the target just addedà Click Publish
     Note: When a Product is in the staged state, it is not yet visible to, or subscribable by any developers.

    d.   If there is no catalog in the organization, you need to create a catalog. (A catalog contains a collection of API Products and is associated with a Developer Portal)




    In order to access on premise database from Bluemix, we need to provision secure gateway service in Bluemix.

    ¬†a.¬†¬†¬†¬†¬† In Bluemix console, search for gateway and select ‚ÄúSecure Gateway‚ÄĚ. IBM Secure Gateway for Bluemix enables users to integrate cloud services with enterprise systems.

     b.     Click create , accept default plan and ADD Gateway (bookgw) Рit will generate Gateway ID and token (make a note of it)


    c.      Click on Add Clients and install the appropriate Setup Secure Gateway client using IBM Installers or Dockers or DataPower

     a.      Open Secure Gateway on Client http://localhost:9003/dashboard. Add the Gateway ID and Token noted above.new-6

    d.     Open Secure Gateway on Client http://localhost:9003/dashboard. Add the Gateway ID and Token noted above.


    e.     This will enable the secure tunnel between the Bluemix and the client. ADD Destination, Resource Host , PORT and Protocol. Allow ACL from the secure client. 


    f.      Make a note of the Cloud host and port values. To access on-premises database instance, applications must be updated with cloud host and port that was assigned to the secure gateway services.


    g.      Test the connectivity, Test the API and verify the response.

    Ensure that the JSON formatted response for the search operation ‚ÄúBooks By Author‚ÄĚ API is operational, enter the URL: https://api.eu.apiconnect.ibmcloud.com/leenakushwahainibmcom-dev/sb/api/TITLE0s?filter[where][AUTHOR_NAME]=John&filter[limit]=3

    and verify that the API provides a response that is similar to the following example:


  10. To access in Developer Portal

    API Connect provides a custom Developer Portal along with advanced analytics. The Developer Portal is an entry point with which consumers can browse and subscribe to APIs.

    a.        You can specify policy settings to limit the use of the APIs exposed by the Plan.

    The Developer Portal includes an administrator interface that can be used by the API Provider Portal to customize the user experience. The Portal administrator can customize the theme for their business, create and control forums, and customize content.

     b.     Select the <Catalog> that is created.àClick the Settings icon à Click Portalà Select IBM Developer PortalàMail will be sent to you in two hours with link for developer portal.


    c.      Consumers acquire API credentials by registering applications in the Developer Portal. They can also monitor API usage. Application developers gain access to APIs by registering applications to access Plans.   

     Click on the developer portal link and verify the API response.




    The API Connect for Bluemix solution provides a platform to create, test, manage, and publish one or more Products to expose an API on the Developer Portal. To drive interactive systems of engagement, Bluemix hybrid cloud solutions allow provisioning a secure gateway that securely exposes the data from systems of record.












    Andrew Wack – An architect and expert for IBM System p Cluster Testing. He played a key role in identifying appropriate test techniques, tools and guidelines to enable better test coverage and resources requirements for the test effort. Andrew can be reached at awack@us.ibm.com

    Leena Kushwaha – An Openstack SME and storage consultant. Involved in evaluating, establishing and conducting proof of concepts for Hybrid Cloud Solutions. Leena can be reached at leena.kushwaha@in.ibm.com.

1 comment on"API Connect: Leveraging IBM Bluemix Hybrid Cloud Solution to integrate SOE & SOR through integrated API Services."

  1. Leena, Good Work!
    Now that you have exposed a new REST API in the Developer Portal, application developers can definitely benefit from that.
    It is a good learning for developers to understand the process of creating, managing and securing APIs.

Join The Discussion