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.
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.
Login to API Designer
¬†Changed the directory to ‚ÄúBookstore‚ÄĚ (created in previous step) and run # apic edit
This redirects to the browser: http://127.0.0.1:9000/. 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.
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
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.
- Name: Datasource_name
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
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.
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.
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)
Adding SECURE GATEWAY SERVICE
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.
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:
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.
SUMMARY & REFERENCES
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 firstname.lastname@example.org
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 email@example.com.