In this blog, will be demonstrating the process of creating flows for an API on IBM Cloud in IBM App Connect Enterprise v11. The implementation focuses on exposing database table hosted as REST API quickly using IBM App Connect Enterprise v11 on IBM Cloud.
Pre-requisites:
IBM Cloud account (IBM Cloud | IBM)
IBM App Connect Service (Lite edition) subscribed on IBM Cloud
Any Relational Database with table (DB2 Service created on IBM Cloud used in this demonstration)
Access details for connecting to the database.
Please find the steps for creating the flow for an API
1. Accessing IBM App Connect on IBM Cloud
Log into IBM Cloud account to access IBM App Connect service (IBM Cloud | IBM)
From the IBM Cloud dashboard / Resource List, access the IBM App Connect service that has been provisioned for your account
Click on the service name corresponding to your App Connect service subscription on IBM Cloud to access the App Connect service. From the IBM App Connect Service page, click on Launch App Connect button to navigate to dashboard / home page of your IBM App Connect Service.
A new window / tab opens up in the browser taking you to the home page / dashboard of IBM App Connect Service.
2. Configuring Cloud Connector to connect to Database
Now that we have launched our IBM App Connect service, we need to link it with our database (in my case, DB2 service hosted on IBM Cloud), the tables of which we want to expose by creating flows as an API. For that, navigate to the catalog of cloud connectors provided by IBM App Connect, by clicking on the Catalog option in the left-side navigation menu.
In the Catalog page, under Applications tab, search for your database. In this demonstration, since we are using IBM DB2 database, I will be searching for db2 to access the respective connector.
In the appropriate database connector section, click on the Connect button to configure the integration / connectivity between IBM App Connect service and the database.
The following section covers the connection configuration for IBM DB2 hosted on IBM Cloud. Details required for configuring DB2 connectivity can be obtained from Service Credential created for IBM DB2 service on IBM Cloud.
On successful connection with the database, the corresponding database account get added and listed as shown in the below image.
3. Creating Flow for an API
Now to create the flow, navigate back to the home page / dashboard by using the appropriate menu option from the left side navigation bar
Click on Create flows for an API option from the home page
Or select the "Flows for an API" option under New button from the dashboard page
In the flow editor that gets opened, provide the appropriate name for the API, which in my case I have provided as cardsAPI, as this API will be used for maintaining customer cards information in the database table.
3.1 Defining API: Add Models and its Properties
Provide the name of the model that represents the resource (business entity) you will be exposing via the API. In this illustration am naming the model as cards. Click on Create model button to create it.
In the model editor page, under Properties section of that model, to import all the properties of cards model from the corresponding database table, click on "Select properties from applications" option
In the pop window, application to which connection has been established from IBM App Connect from Catalog page will be listed.
Select the database connector appropriate to your database from the list shown, upon which all the tables from the database will be fetched and listed.
Expand the table that corresponds to the model you have created, in order to see all the columns of that table. Click on Select All to select and then on Add properties button to import all the columns as properties for the model.
All the table columns gets added as properties to the model with the column names as the properties name.
Modify the added property names to make more meaningful and user friendly as appropriate.
3.2 Defining API: Add Operations for the Models
Now that model has been created with all its properties, we can now define the operation that we would like to perform with that model via the API. For that, in the Define page of API, select the Operations tab to add operations on the models we have defined.
Select and add the required operation from the drop-down under the operations section. For instance, for my requirement to add and store new card in the CCMASTER table, am selecting the operation Create cards (typical naming of the operation will be based on the action to be performed on the model defined)
When the selected operation is added, you could see the resource path as well the HTTP method associated with that particular operation. In this instance, HTTP Method as POST and resource path as /cards
3.3 Implementing API Operation
To add implementation logic to the operation, click on the Implement Flow button next to the operation added. Flow editor is opened with the Request node & Response node and showing the sample structure of the Request body constructed based on the API model.
To add the processing logic in this basic flow, click on the plus symbol after the Request Node in the flow editor as shown in the image below
For logging the request message, we are going to use the log node (under Toolbox section) to create custom logging messages. Select the Log node (under the Toolbox section) to get the node added into the flow after the Request node.
Configure the Log node with the Log Level and Log message as shown. From the drop-down of Log Level property, select the option Info for logging level. In order to refer to the context variables available for mapping or to read the incoming request message, select the Insert Mapping icon next to the properties and select the suitable context object / property. For instance, here we are creating log message by combining the static text "Received following request to add new card - " and the actual request message stored in the Object variable referring to Request body parameters.
After logging the request message, next step in the flow is to perform the actual operation on the database table, which in our case is to insert the input card data into the CCMASTER table of DB2 database. To achieve this, click on the plus symbol after the the Log node in the flow editor, and search for the DB2 applications (under the Applications section). From the possible actions available for the DB2 applications, click on show more actions to see the tables available in the database.
Expand the table corresponding to our API model, and select the suitable action in line with the operation we added to the flow. For e.g. in this scenario, we will be selecting the action Create CCMASTER record action to insert the card details into the database table
Once the DB2 action is added to the flow editor, configure the action by creating mapping between the request message fields and the database table column. For this, in the DB2 action configuration against each fields / properties, click on Insert Mapping button / link and select the suitable field / property of Object{} from the list of Available Mapping under Request Object Parameters: Object. Repeat the step for mapping all the database columns with the corresponding Request Object parameters.
Now we have to configure the Response node for the response that we want to send back to the client. Click on the Response node to get to its configuration page, and do the mapping for the response body as we did earlier. But this time from the Available Mappings section, for cardNumber field select the property CARDUM under IBM DB2 Create CCMASTER record action output. For all the other fields or properties in the response body, select the appropriate field / property under Request body parameters node output.
Change the Status Code to 201 under Response Header in the configuration page of Response Node.
With this, we have completed the flow implementation for our operation. Click on Done at the top right corner of the page to exit the implementation page of the operation.
3.4 Manage the API
Now that the Define and Implementation of the API is completed, we can configure the Management of the API. For this click on the Manage tab of API editor, which will then show you various management sections of API like API Info, Rate Limitation & Security applied etc.
If you want to apply rate limitation (throttling) on the number of requests per API Key (client) for the API, Enable the option Limit API call rate on a per-key basis and provide the value for Maximum call per Unit of time, like 5/second.
For testing & consuming the API that we have developed as an external consumer / client, navigate to the bottom of the page and under the section "Sharing outside of Cloud Foundry organization", click on Create API Key and documentation link in order to generate the unique API key for the consumer / client and the documentation link for them.
In the Create API Key window, specify the name and click Create. New entry will be added with the API Key and the API documentation link against the name that we specified.
Now the flow is ready, we can start the API for consumption by selecting the Start API option at the top as shown below. Once the flow comes to Running state, we can now start testing / consuming it.
3.5 Testing the API as Client / Consumer
Copy the API Documentation link from the Manage page of the flow that we have created and open it separate browser window. Also copy the API Key value for testing / invoking our API endpoint at later stage.
From the API documentation page, as a client / consumer we will be able to download the Open API Definition (swagger) file for the API and also get overview of the operations offered in the API in detail.
To try or test an API operation, select the API operation, for e.g. POST /cards link and click on Try it tab.
In the Try it tab, under security section, paste the API key value that we copied earlier, and under the parameters section, in Body, click on Generate option to generate the sample request data. Modify the generated request body as per your requirement and click on Send button to invoke the API operation.
Output of the API operation invocation that is the response received will be shown.
Logs of the IBM App Connect on cloud can be accessed by clicking on Logs option from the left-hand side navigation in IBM App Connect Page
In this illustration, we focused on creating a flow for an API in IBM App Connect v11 on IBM Cloud. Hope this was helpful.
Leave your valuable comments in the Blog or you could mail your thoughts / comments / suggestions to reachnebula@learnibmesb.com.
Comments