L02

IBM Integration Bus

Developing a REST API service

Featuring:

The REST API tools for IIB

Testing with Swagger UI

June 2015
Hands-on lab built at product
Version 10.0.0.0
IBM Integration Bus V10 Workshop June 2015

1. PREPARE THE IIB NODE ........................................................................................................... 3

1.1 OPEN THE W INDOWS LOG MONITOR FOR IIB............................................................................ 3

1.2 CREATE AND CONFIGURE A NEW NODE FOR REST ................................................................... 4

2. CREATE THE REST SERVICE ................................................................................................... 5

2.1 EXAMINE THE EMPLOYEESERVICE JSON DOCUMENT ............................................................... 5

2.2 IMPORT THE EMPLOYEESERVICEINTERFACE SHARED LIBRARY .................................................. 6
2.3 DEVELOP THE NEW REST SERVICE ......................................................................................... 7
2.4 IMPLEMENT THE GETEMPLOYEE OPERATION ........................................................................... 12

3. TEST THE EMPLOYEESERVICE REST API ............................................................................ 23

3.1 DEPLOY THE SERVICE ........................................................................................................... 23

END OF LAB GUIDE ..................................................................................................................... 29

Page 2 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

1. Prepare the IIB Node

1.1 Open the Windows Log Monitor for IIB

A useful tool for IIB development on Windows is the IIB Log Viewer. This tool continuously
monitors the Windows Event Log, and all messages from the log are displayed immediately.

From the Start menu, click IIB Event Log Monitor. The Monitor will open; it is useful to have this
always open in the background.

This tool is not shipped as part of the IIB product; please contact us directly if you would like a
copy.

Page 3 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

1.2 Create and configure a new node for REST

The IIB support for the REST API requires some special configuration for the IIB node and
server. To ensure this scenario does not interfere with other scenarios, you will create and use a
separate IIB node.

1. Support for REST requires the use of the embedded HTTP listeners, rather than the node-
wide listener.

Additionally, the IIB node has to be configured for Cross-Origin Resource Sharing (CORS).
For details on this, please read: http://www.w3.org/TR/cors/.

To configure these items, we have provided a script. In an IIB Command Console, change
directory to
c:\student10\REST_service\install

Run the script file:

Create_RESTNODE

Accept the default values for the IIB node name (RESTNODE).

This script will create the new node, and run two key commands:

 Enable HTTP embedded listeners. The REST support is only provided for embedded
listeners, not the node-wide listener:

mqsichangeproperties RESTNODE
-e default
-o ExecutionGroup
-n httpNodesUseEmbeddedListener -v true

 Enable Cross-Origin Resource Scripting for REST. This is required when testing with
the SwaggerUI test tool. See http://en.wikipedia.org/wiki/Cross-
origin_resource_sharing for further information.

mqsichangeproperties RESTNODE -e default

-o HTTPConnector
-n corsEnabled -v true

The script will also configure the JDBC parameters for connection to the SAMPLE database,
which will be used in this scenario.

When the node is fully restarted, you will see the following messages on the IIB Event Log
viewer:
BIP3132I: ( RESTNODE ) The HTTP Listener has started listening on port
''4418'' for ''WebAdmin http'' connections. [08/04/2015 09:16:21]
BIP2152I: ( RESTNODE.default ) Configuration message received from
integration node. [08/04/2015 09:16:22]
BIP2153I: ( RESTNODE.default ) About to ''Start'' an integration server.
[08/04/2015 09:16:22]
BIP2154I: ( RESTNODE.default ) Integration server finished with
Configuration message. [08/04/2015 09:16:22]

Page 4 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

2. Create the REST Service

In this section you will create a new REST API service. This scenario will be based on the
EmployeeService example that you may have used in other labs in this series.

2.1 Examine the EmployeeService JSON document

1. In Windows Explorer, locate the file

c:\student10\REST_service\resources\EmployeeService.json

Open the file with the Notepad++ editor (right-click, select Edit with Notepad++).

We have installed a JSON document plugin into Notepad++, so this JSON document will be
formatted for easy reading.

The JSON document has been constructed to define interfaces for the EMPLOYEE and
DEPARTMENT tables.

The main section of the document is a series of operations (GET, POST, PUT, etc),
associated with different types of operation (getEmployee, listEmployees, etc).

At the very bottom of the document are two definitions for Employee and Department, which
defines the precise structure of these elements.

This document will be used as the basis of the REST applications that you will build in IIB.

Look for the variable "employeeNumber", which is referenced in several places in the
document. This variable will be used by the IIB REST application.

Close the editor without making any changes to the document.

Page 5 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

2.2 Import the EmployeeServiceInterface Shared Library

1. The REST service that you will develop will use the EMPLOYEE tables from the SAMPLE
database, and the Map that was developed in the Integration Service lab. However, you will
use a pre-built version of these artefacts, to ensure the REST service is developed
successfully.

Create a new workspace named c:\workspaces\IIB_REST (use File, Switch Workspace to

show the dialogue to set the new workspace name).

In the workspace, import the Project Interchange file:

C:\student10\integration_service\solution\EmployeeServiceInterface.V10.zip

Select both the SAMPLE and EmployeeServiceInterface projects to import.

When imported, you will see the Shared Library like this:

Page 6 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

2.3 Develop the new REST service

1. In the workspace, create a new REST API service.

2. Name the new service EmployeeService_REST, and click Next.

Page 7 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

3. Using the Browse button, import the JSON document

c:\student10\REST_service\resources\EmployeeService.json

Click Next.

Page 8 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

4. The summary window will show you all of the REST operations that were defined in the
JSON document. These operations were constructed to match the EMPLOYEE and
DEPARTMENT tables in the SAMPLE database.

Note there is an operation named getEmployees (ie. retrieve a list of all employees), and an
operation named getEmployee. This lab will implement the getEmployee operation.

Click Finish.

Page 9 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

5. The operations have now been imported into the IIB Toolkit. The import process has also
created a base REST application and a message flow that implements the REST service.

Expand each operation. You will see that you can implement the operation by clicking the
"Implement the operation" link.

Page 10 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

6. Before proceeding with the implementation, the REST service has to reference the required
Shared Library. This is because it needs access to both the schema definitions and the IIB
getEmp map that are stored in the library.

In the navigator, right-click the EmployeeService_REST service and select Manage Library
references.

Tick EmployeeServiceInterface and click OK.

Page 11 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

2.4 Implement the getEmployee operation

1. You will now implement the getEmployee operation.

In the Operations list, locate getEmployee and click "Implement the operation".

This will open the subflow editor. Each operation is implemented with a separate subflow.

NOTE - Select the getEmployee operation in the /employees/{employeeNumber} section.

Do not confuse this with the /getEmployees operation in the /employees section, just
above.

Page 12 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

2. Drop a Mapping node onto the flow editor.

Name the new map "getEmp".

Page 13 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

3. This mapping node will actually be the getEmp map that is already built and available in the
EmployeeServiceInterface, so you must change the properties of the node to reference this
map.

Highlight the map, and select the Properties of the Map node. Click Browse to select the
getEmp map from the shared library.

If you are using the prebuilt version of the Shared Library, you will also see a map called
updEmp.

Click OK.

Page 14 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

4. REST GET operations will be contained within the HTTP header part of the incoming
message. When IIB receives such an incoming message, it extracts the REST parameters
and places them into the Local Environment. IIB v10 has introduced a new part of the
LocalEnv called REST.

The getEmp map requires its input in the form defined by the EMPLOYEE schema. To
construct the message in this format, you will develop a new mapping node to obtain the
incoming parameter for the getEmployee operation. The mapping node will use this
information to construct a message in the format required by getEmp.

Drop two further nodes onto the flow and connect as shown:

 Mapping node - name this extractKeyFromLocalEnv

 Trace node (it's in the Construction folder)

Page 15 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

5. Open the extractKeyFromLocalEnv map, and click Next at the first window.

For the map inputs and outputs, make the following selections:

 Input
o IBM supplied message models - BLOB (the subflow will obtain its
information from the LocalEnvironment, and there is no need to parse the
message payload)
 Output
o EmployeeServiceInterface, XML schemas - EMPLOYEE

Click Finish.

6. The basic mappings will be shown.

Page 16 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

7. For a REST GET operation, the employee key will be available in the LocalEnvironment. For
the map to access the Local Environment, you must explicitly add this header to the
Message Assembly.

On the input Message Assembly, right-click and select "Add or remove headers and folders".

Select the LocalEnvironment and click OK.

Page 17 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

8. Expand the Local Environment and the REST section (located near the bottom of the Local
Environment).

Incoming REST parameters will appear under the REST/Input/Parameters element, so the
definition of this element needs to be added here.

Right-click the "any" element and select "Add User-Defined".

9. Name the new element employeeNumber. Note, this has to match the precise name and
case of the JSON employeeNumber element that you saw in the JSON document.

10. The new element needs to be mapped to the output EMPLOYEE/EMPNO message.

Unfortunately, expanding the Local Environment has probably meant that the output
message has disappeared from the map display. To handle this, perform a "Quick Link".
Right-click employeeNumber, and select Quick Link.

Page 18 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

11. A pop-up window will show the available output message.

Collapse the Properties element, and in the EMPLOYEE element, select EMPNO.

12. A Move transform will be generated. If you wish, you can use the QuickFix to correct the
cardinality warning message (hover over the small light on the Move transform, then select
"Set cardinality to first index").

Save and close the map.

Page 19 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

13. One final node is required. In the flow editor, drop a third map node onto the flow and name it
convertXMLToJSON. Connect as shown.

The map is required because the output needs to be sent back to the originating REST
request in JSON format. (The getEmp map produces an output message in XML format).

14. Open the new map.

Click Next at the first window, and for the inputs and outputs, make the following selections:

 Input
o EmployeeResponse
 Output
o IBM supplied message models - JSON object

Click Finish.

Page 20 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

15. The output JSON message needs to be Cast as EmployeeResponse. Fully expand the
JSON output, and right-click the final "any".

Select Cast.

16. At the Type Selection, choose EmployeeResponse.

Click OK.

Page 21 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

17. Create the following mappings:

 Map DBResp to DBResp.

 Map EMPLOYEE to EMPLOYEE

The result will be:

18. Save and close the map.

Save the subflow.

Page 22 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

3. Test the EmployeeService REST API

This chapter will show you how to use the SwaggerUI tool to send a REST request into the REST API
service that you have just created.

3.1 Deploy the service

1. In the navigator, deploy the EmployeeServiceInterface shared library to RESTNODE/default.

Then deploy EmployeeService_REST to RESTNODE/default (drag/drop or right-click,

deploy).

2. Open the IIB web UI by right-clicking RESTNODE and selecting Start Web User Interface.

Page 23 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

3. You will be switched to the default browser. Fully expand RESTNODE, down to the
EmployeeService_REST, as shown below.

Under EmployeeService_REST, click "API", which will show you the available operations in
IIB and whether they have been implemented. Check that you have implemented the correct
operation.

It will also show you the URLs for local and remote invocations, and the REST API
definitions (the .json file).

4. On the "Remote URL for REST API definitions", right-click and select "Copy Link Location".

Page 24 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

5. In Firefox, open a new tab, and open the SwaggerUI tool (using the bookmark in the REST
folder).

By default, this will open the Petstore Swagger document.

6. In the entry field, paste the contents of the clipboard and click Return (or click Explore).

The two high-level functions, departments and employees, will be shown.

7. We are concerned with the getEmployee operation so click "List Operations" to show the
operations related to employees.

Note that SwaggerUI does not have any knowledge at this point of whether the operation has
been implemented.

Page 25 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

8. Expand the GET employees/{employeeNumber} operation by clicking it.

The employeeNumber will show the expression (required). Replace this with a suitable
value, say 000010.

Page 26 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

9. When you have provided an employeeNumber, click Try it out!

If successful, the returned data will look something like this. Note the database response
information (user return code, number of rows returned), as well as the user data.

Page 27 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

10. Provide an employeeNumber that does not exist, for example 000012 (but make sure you
use an employeeNumber that has 6 characters).

You will see the service has worked (UserReturnCode = 0), but no data has been found
(RowsRetrieved = 0).

Page 28 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks

IBM Integration Bus V10 Workshop June 2015

11. Now use an invalid length key, for example 0000102, which has 7 characters.

You will see that although the request completes, the UserReturnCode = -1. This indicates
that a database error has occurred, and the relevant SQL errors have been passed back to
the REST client. In this case, the SQLCODE of -302 indicates that the key field is too long

END OF LAB GUIDE

Page 29 of 29 Developing a REST API service Version 10.0.0.0

Provided by IBM BetaWorks