IBM API Connect

In the previous tutorial we learnt how to write a NodeJS service that connects to an IBM Cloudant database. Continuing with IBM technologies and with the previous tutorial, we will learn here how to expose the service previously created as an API through IBM API connect platform and how to subscribe to our created API through developer portal and consume it . The steps in this tutorial are simple and easy to follow .

You can check out this post on the whys and hows of API management in general, and the different API management platforms to possibly use before starting this tutorial. Or, you can check out this cool and always relevant but old video by IBM on API connect if you are totally new to API management .

1 – Setup IBM API Connect

We need to install the APIC Developer Toolkit that offers the ability to run and test APIs locally before publishing them to bluemix along with other rich capibilities. We also need to install Node and Docker as pre-requisite components .

• Install Node.js

The API Connect developer toolkit  is built on Node.js technology. So we first need to ensure we have Node.js running:

npm -v

If Node.js is not installled on your machine , proceed to install it, then update your version of npm as follows :

npm install npm --global

•  Install Docker
  

The need to install Docker here is due to the the Docker version of the DataPower API Gateway that’s included in the APIC toolkit for purpose of local tests of the APIs . So we first verify that Docker is running:

docker ps

If Docker is not installed on your workstation, you can follow the instructions on the Docker website to install it.

•  Install the APIC Developer toolkit

Use the node package manager to install APIC developer toolkit as follows :

npm install -g apiconnect

Once complete you can verify the installation with :

apic -v

As we will initially test the API offline then publish and run it on IBM Bluemix, we will need to setup Bluemix as follows :

• Create a Bluemix account and setup a Bluemix organization

Create a new account on www.bluemix.net and login. On login, you will be prompted to ” Create organization “

You will be later prompted to create a space. Create a space named dev  :

• Enable the API Connect service on your Bluemix account

On your IBM bluemix dashboard click on Create resource and search ” API Connect “. You can choose the ” Lite ” pricing plan and  you will be redirected to the API drafts after creation of the service.

• Create a developer portal instance for your API connect catalog

From the drafts view, click on menu and choose the dashboard option .

Click on the Sandbox Catalog and go to settings :

Click on the Portal option in the left-hand menu palette, select the IBM Developer Portal option and click on save on the top right corner .

Take note of the Portal URL you see on this page as you will need later in step 3 .

2 – Create your API on IBM API Connect

We will use the APIC toolkit to generate a template for a microservice application which provides access to certain data via a RESTful API .

• Create a simple microservice application

Building our microservice application we will use the Loopback framework which comes with the APIC developer toolkit. Loopback enables developers to create scalable APIs and conforms to the Swagger 2.0 specification . You can check out more details about Loopback apps seperately . For now, let’s use the APIC toolkit to create a Loopback app as follows :

apic loopback

You will be prompted to enter you app name, path and type . We will choose empty-server app for this step :

launch the API Connect toolkit dashboard to manage your apps and APIs . Run the following command :

apic edit

The dashboard will be launched on your default browser, and you can go to APIs to see your recently create app as follows :

• Create a REST API definition using IBM API Connect Designer

As a first step we need to create a data source in order to build data models for our API data . Loopback framework is a data model driven framework, so we will be creating a data model which is a backend data repository for our microservice’s data. The properties for the data model will become the JSON elements of the API’s requests and responses .

For this tutorial we will use MySQL, but as you see in the next screenshot, when creating a new data source through the APIC dashbaord you will have to choose from either MySQL, IBM Cloudant, MongoDB, PostgreSQL or more other types of connectors .

As first step, we will go the APIC toolkit and select Data sources → Add , then type in the data source name and select the connector type as follows :

Click on the Install Connector link to download the connector module for MySQL data sources as you will be prompted . Once installation done, complete the connector configuration properties for with your MySQL database details or with the following values for this demo:

URL: leave it blank

Host: demo.apicww.cloud

Port: 3306

User: student

Password: Passw0rd!

Database: think

At this step, we will inspect the created data source to build a data model for whatever data or “items” we need to expose through our API. From the recently created data source’s configuration ui, click on Discover Models . The API Connect Toolkit will query the table structure of the MySQL data source and allow you to select the desired properties to build your data model from :

Click on Select properties  . You will have a list from which to select the desired to select the properties you need to build your API’s data model from .

Keep the default, click on Select → Generate .

At this stage , our microservice application presents the ” properties ” we selected to create data models from as API response / request objects . We need to test the API as a next step .

• Run and test your API locally

The  API Connect environment in Bluemix uses the IBM DataPower API Gateway to enforce API policies. You can test the API with a local version of DataPower running in Docker prior to publishing the API to the cloud.

Click on the menu icon in the top left hand corner of the screen and select the TestAPI project to return to the API definitions section. Open the TestAPI definition and Select DataPower Gateway from the palette on the left.

Then click on the Run button of the top left corner of the dashboard .

If this is your first time starting an application with a DataPower Gateway policy, the toolkit will need to download the docker image, which will take some time . Once you see Running status near the Run button, you can pass to review your API by clicking Explore on the  top right corner .

We can see here a list of the paths for our API . These are the paths and operations that were automatically createdby the LoopBack framework simply by generating the item data model. The operations allow clients the ability to create, update, delete and query the data model from the connected data source.

You can go through the different paths and explore the ” call operation ” tool to test each path and check the response/request headers . Once done you can stop running the API locally and pass to the next step to host it on Bluemix .

3 – Consume your API through IBM developer portal

• Publish the app to bluemix

At this stage, we have a Node.js microservice application that is configured with a data model backed by a MySQL data source.
On the top right corner of the APIC dashboard you can clearly see a Publish button . You can click Publish to be prompted the following :

Login to Bluemix if needed and select the Bluemix organization we created on setup 1 and the Sandbox catalog . Add your app name ,

then make sure you check the Publish application and Stage or Publish Products checkboxes to publish both the API and the application together :

Once the publish process is complete, you can check your Bluemix account to see the new node.js app added to Cloud Foundry apps list as below : 

As a last step here, we will verify the application runtime URL . Go to your APIC dashboard’s API definition then to Properties section. Notice that there is two properties have been added to the API definition: runtime-url, and invoke-tls-profile. Expand the runtime-urlproperty and notice that for our Sandbox environment, the URL has been set to a new route for our application running in the Bluemix Cloud.

• Register a test app

Now we will use the Developer portal instance created on step 1 : launch the developer portal through the URL you saved on step 1 . Once on your developer portal, click on Create an account on the top right corner, and complete the registration form to set up the login to your API Portal account .

On the Developer portal, go to Apps → create new app , add your app name and submit .

Once your application is registered in the IBM API Connect system, it is assigned a unique set of client credentials. These credentials will be required on each API request in order for the system to validate your subscription entitlements .

Save the Client Secret and Client ID for further use ,  then click on the API Products tab , choose your API, and click on Subscribe to be ready for the next step of test .

Test the API

Your API is now running on bluemix and ready to be used . You can test it through the API Developer Portal by going to the API definition on the portal , and invoking each operation you want to test. You will need Client Secret and Client ID  generated in previous step for the calls .

The portal provides example request options for various programming languages and an example response payload, as well as various details about the request parameters and links to the response schemas .

After creating a microservice application using the APIC toolkit, creating a REST API definition of your microservice, testing the API locally, hosting it to bluemix and running / testing it , you will need to pass to securing your API and protecting the exposed resources . This will require a new tutorial which I will publish next to this one .