April 30, 2015 | Written by: Belinda Vennam
Share this post:
Bluemix SmartBooks presents a catalog of books for sale, can suggest interesting books to users based on a Twitter handle, and will store purchased books into an orders database. To suggest books based on Twitter handle, the application consumes an API from a business partner, which was published to Bluemix and shared with the Bluemix SmartBooks development team using the API Management service.
Check out Bluemix SmartBooks in action
You can create your own version of Bluemix SmartBooks. This blog post will cover all the steps, including the underlying architecture, creating your own instance of SmartBooks, and customizing it.
Step 0: What You’ll Need
Below is what you will need to create your own version of Bluemix SmartBooks:
- A Bluemix account — if you don’t already have one, sign up for the free trial.
- A Twitter application — you will need a Consumer Key, Consumer Secret, Access Token Key, and Access Token Secret. These values are given once you create a Twitter app.
- A Google API Key — instructions can be found here, This is not required immediately, but your Google Books API usage will be throttled pretty quickly without it.
Step 1: Understand SmartBooks Architecture
API Management on Bluemix defines two roles, a Provider and Consumer. For this example, we’ll refer to the developers of them them as two fictional companies, APIs Inc. and Bluemix Smartbooks.
API Provider: APIs Inc.
- The API Provider has provided an Interests API. This API takes as input a Twitter handle and outputs an array of interests. See the Twitter Interest API documentation for more details.
- The API Provider wants to implement rate limits and interesting analytics around the APIs they own, so they decide to use API Management on Bluemix. They can now share their API on Bluemix to API consumers like Bluemix SmartBooks>.
API Consumer: Bluemix SmartBooks
- Bluemix SmartBooks is an e-commerce application based on the microservices architecture design pattern. The concept of microservices is simple – an application is broken into multiple independent applications, where each application has a clear purpose. The applications talk to each other using HTTP over REST or a message queue. Each of these applications can be written in whatever language is best for its job. Our application is based on the previous e-commerce sample, found here. For a more in-depth overview, check out the previous blog. The SmartBooks application is divided into an orders service, a catalog service, and a UI layer to tie it all together.
- A backend RESTful API to track all store orders. This JavaEE application stores orders in a persistence entity that can be used with an internet-accessible database or in conjunction with the Bluemix Secure Gateway service to securely access databases inside an enterprise.
- The catalog service is an API to track all of the items available in the store. This is written in Node.js with Express. The catalog of items is persisted in a Cloudant database.
- The UI application is a simple UI layer displaying all items in the store catalog, creating orders, and invoking the Interests API mentioned below. This UI will call all three APIs, and is written in PHP.
- After the store application was written, the developers wanted to personalize the catalog suggestions!
- Their API Provider business partner had provided a few different APIs, and they saw the interests API. Seemed like a perfect fit for personalizing the catalog, so they decided to pull it into their application.
- This interests API was provided through API Management, enabling the API provider to provide rate plans, get analytics on their API usage, as well as share their APIs to Bluemix.
Step 2: Set up your own instance of SmartBooks
To set up your own version of SmartBooks, you will need to play the API Provider, APIs Inc., and the API Consumer, Bluemix SmartBooks.
As the API Provider, you need to deploy the interests API. This is an Express-based API which takes as input a Twitter handle and provides as output an array of interests based on that handle. This code is provided on JazzHub.
- Deploy interests API application, by clicking the button below.
- You will have to make a quick update to the config file and redeploy this app before the Twitter interests API will function. Click Edit Code.
- Find the config file in
config/default.json. Insert the values from the Twitter application required as a prerequisite to this tutorial.
- Once these values are added in the
default.json file, check in your changes by clicking the git icon in the left side bar.
- You will need to commit and then push your changes. After this is done, you can now Build and Deploy the new version of your app by selecting the Build and Deploy button in the upper right corner.
- You now have a Twitter interests API! Quickly play around with the interests API by clicking the link to your app on the Build and Deploy page.
- You can test out this API by going to the Swagger docs, and entering in a Twitter handle.
- Follow instructions from our getting started with API Management tutorial to provision the API Management service on Bluemix, add your API and create a rate plan, and deploy your API to Bluemix.
- The API is now available for consumption on Bluemix for your business partners.
As API Consumer, Book Sellers Inc:
- The source is provided as a set of three separate applications: A catalog API app, an orders API app, and a UI application. You can check out, clone, and play around with the code for each of these individual pieces from their git repositories on IBM DevOps Services.
- Deploy Catalog API by clicking the Deploy to Bluemix button below.
- Click View Your App and Note the route of this deployed application for later use:
- Deploy Orders API by clicking the Deploy to Bluemix button below.
- Note the route of this deployed application:
- You may skip steps 3, 4, and 5 below if you are not interested in storing book orders or you would like to save this step for later.
- The Orders API can be connected to any JDBC compatible database you want to store your order records in. To configure a database connection, you will again need to edit the code using the same process as with the Twitter API.
- In the file tree on the left, navigate to
/src/META-INF/persistence.xml and modify the <properties> list with either the direct database connection parameters or the host and port information of a Bluemix Secure Gateway destination that points to your database.
- Commit and push the persistence changes to git, and then redeploy the application to start using the new database connection.
- Deploy UI application by clicking the Deploy to Bluemix button below.
After deploying, You will also need to edit a few of values in the UI application.
- In index.php change the variable
$catalogRoute to the route of your catalog API.
submitTwitter.php, change the variable for
$twitterAPIURL to reflect the URL you were given from APIm, as well as the client id & secret. All of this information can be found in the
VCAP_SERVICES for the Node.js app that your interests API is associated to from the API Provider instructions.
submitOrders.php, change the variable
$ordersRoute to point to the orders route of your orders API.
- Once these values are added, check in your changes by clicking the git icon in the left side bar.
- You will need to commit and then push your changes.
- After this is done, you can now Build and Deploy the new version of your app by selecting the Build and Deploy button in the upper right corner.
- At this point, your SmartBooks application should run, with suggestions providing books from the Google Books API, and Orders being stored to a backend Oracle DB! As the API Provider, you can go check APIm to see analytics information on API Usage!
Step 3: Build on top of SmartBooks
By now you have an excellent starting point for an application. You have created an interests API based on a Twitter handle, created rate plans around that API using API management, and then shared the API to Bluemix for use by yourself or partner organizations. You’ve created a simple e-commerce microservices based application, consumed the Twitter interests API from API Management on Bluemix, and stored your orders in an Oracle on-premises database. This application has a number of different possible extensions, and we look forward to seeing what you come up with!