Creating a REST API which exposes an existing SOAP Service with

Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
Creating a REST API which exposes
an existing SOAP Service with
IBM API Management 3.0.0.1
© 2014 Copyright IBM Corporation
Page 1 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
TABLE OF CONTENTS
OBJECTIVE....................................................................................................................................3
PREREQUISITES...........................................................................................................................3
CASE STUDY.................................................................................................................................3
USER ROLES.................................................................................................................................4
BEFORE YOU BEGIN....................................................................................................................4
LOG INTO THE API MANAGER....................................................................................................6
CREATE AN ACCOUNTS REST API............................................................................................7
CREATE A BALANCE ASSEMBLY RESOURCE.......................................................................11
ADD A WEB SERVICE INVOKE OPERATION TASK.................................................................15
BUILD THE ACCOUNTS API RESPONSE.................................................................................20
ADD THE BALANCE RESOURCE TO THE PUBLIC PLAN......................................................23
TEST THE BALANCE RESOURCE............................................................................................27
SUMMARY....................................................................................................................................30
© 2014 Copyright IBM Corporation
Page 2 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
Objective
In this tutorial, you will learn:
 How to expose an existing SOAP service as a REST API
Prerequisites
This tutorial is the fourth in a series, it builds on the Creating a proxy REST API with IBM API
Management 3.0.0.1, Creating an assembly REST API with IBM API Management 3.0.0.1
and Creating a SOAP API with IBM API Management 3.0.0.1 tutorials.
For more information about this series and other tutorials please see:
http://developer.ibm.com/apimanagement
Case study
Bank A has an existing set of SOAP based services that they would like to expose through APIs
in order to foster growth within the mobile and device market. The Bank A business team knows
that an increased mobile and device application presence will enhance their brand image and
increase customer satisfaction.
The Bank A business team have had requirements from their mobile application developers to
expose their existing web services as JSON REST APIs. JSON payloads are smaller than the
same data in SOAP format which reduces the amount of bandwidth required for mobile
applications. JSON is also an easier data format to work with in JavaScript which is a popular
programming language for mobile development.
After considering building their own API management solution, the Bank A technology team has
decided to implement an IBM API Management solution as it will allow them to enter the market
quickly at a reduced cost.
In this tutorial you will develop the Bank A API Management solution. The solution will
document, create and implement a new assembly resource to expose the balance enquiry
SOAP service as a JSON REST API resource, as shown in Figure 1 below.
© 2014 Copyright IBM Corporation
Page 3 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
Figure 1 – Balance Enquiry SOAP to REST Conversion
User roles
IBM API Management 3 allows different roles to be assigned to users. For more details of the
different user roles and descriptions of them please see the following page in the Knowledge
Center:
Adding users and assigning roles
The tutorial has been written assuming that you are an Administrator or Organization Owner. If
you have another role, such as Product Manager or Developer then some of the required
functionality will not be available to you so you may need to contact an Administrator or
Organization Owner to perform certain actions, such as:
•
The ability to edit APIs is not available to Product Managers.
Before you begin
Access the Bank A Backend Service
Before you setup an API in the IBM API Management product, you need to verify that the
backend account service is working and accessible. Remember that the goal is to expose this
service as a managed API on the IBM API Management platform.
© 2014 Copyright IBM Corporation
Page 4 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
1. Open a new browser tab and navigate to the URL
http://banka.mybluemix.net/home/index.html
2. Click on the Endpoint for the Service titled Account Service (SOAP) to make sure that the
account service is operational. This is the service that you would like to expose via the API
gateway.
3. By clicking on the link you are making a REST based GET call to the account service, which
will return a basic message identifying it as a Web service. Validate that the account service
responds.
© 2014 Copyright IBM Corporation
Page 5 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
4. Click the browser back button, and click the WSDL link for the Service titled Account
Service (SOAP) to ensure the WSDL URL is working correctly.
5. Validate that the account service WSDL is displayed.
Log into the API Manager
To save time, and for the purpose of this lab, an IBM API Management organization has already
been registered for you to use.
6. Open a new browser tab navigate to the URL https://<managementserver>/apimanager
Where <managementserver> is the IP Address or hostname of your management server.
© 2014 Copyright IBM Corporation
Page 6 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
7. Sign in to the IBM API Management platform by clicking entering your credentials and
clicking Sign In.
8. Confirm that you are logged into the correct organization.
9. After you sign in, the API Manager Home page is displayed. The home screen displays
activity graphs for each environment.
Create an Accounts REST API
In the previous tutorial you created a simple proxy of an existing SOAP service. Now you will
use an assembly to expose the same SOAP service as REST to satisfy the requirements from
the mobile application developers. A new API will be required for this since SOAP and REST
resources cannot be mixed in the same API.
© 2014 Copyright IBM Corporation
Page 7 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
10. Click APIs in the navigation pane.
11. Click the + REST button to create a new REST API.
© 2014 Copyright IBM Corporation
Page 8 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
12. Populate the fields as shown in the table below. When complete, click the Add button.
Field Name
Value
API Name
Accounts
Path
accounts/v1
API Description
Operations related to Bank A accounts
13. The Accounts API is added to the list of Draft APIs.
© 2014 Copyright IBM Corporation
Page 9 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
Create a Balance Assembly Resource
14. Click on the Accounts API name to enter the API editor.
15. Check Identify Application Using is set to Client ID.
© 2014 Copyright IBM Corporation
Page 10 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
16. To create a resource that supports a GET operation, click + Resource.
17. Remove the POST method by clicking the cross.
© 2014 Copyright IBM Corporation
Page 11 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
18. Populate the fields as shown in the table below. When complete, click the Add button.
Field Name
Value
Path
{accountId}/balance
Display Name
Balance
Description
Account Balance
19. Now that the balance resource has been defined, click on the Edit icon to edit the resource
details.
20. Enter a description for the accountId parameter as listed in the table below, note that the
required check box is selected as this is a path parameter.
Parameter
Description
accountId
Account Identifier
© 2014 Copyright IBM Corporation
Page 12 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
21. Click on the Response Body tab and paste in the sample JSON response below for the
resource below. Click somewhere else on the screen and the JSON will be automatically
formatted for you.
{
"balance": 1234.56
}
22. Select the Implementation tab and ensure the Assemble tab is selected.
© 2014 Copyright IBM Corporation
Page 13 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
Add a Web Service Invoke Operation Task
23. Click the + icon to add a task to the resource implementation, and select Invoke Operation
from the Web Service section. This will be used to invoke the Account Web Service.
24. Click on the Web Service Invoke Operation to see the Connect panel for this task.
© 2014 Copyright IBM Corporation
Page 14 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
25. Populate the fields as shown in the table below. The WSDL URL can be copied and pasted
from the other browser tab where you viewed the WSDL. When complete, click the Load
button.
Field Name
Value
WSDL URL
http://bankaws.mybluemix.net/services/AccountService?wsdl
Username
Leave blank
Password
Leave blank
© 2014 Copyright IBM Corporation
Page 15 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
26. In the DISCOVER stage of the implementation, the WSDL which has been provided has
been parsed and presented in a form which allows you to select the fields you wish to
expose in the CONFIGURE stage. In this case you wish to map only a single entry (arg0)
into the request message for the getBalance operation of the service.
Expand the AccountService, then AccountPort and select the getBalance operation. and
select only the arg0 input field that will be mapped from the accountId in the URI path
parameter for the API.
27. Select Configure to map the input parameter of your API to the input parameter of the Web
Service Invoke Operation.
© 2014 Copyright IBM Corporation
Page 16 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
28. Click Select Available Value for the arg0 parameter of the Web Service Invoke Operation.
29. Map the accountId from the API you are creating to the arg0 of the Web Service Invoke
Operation by selecting accountId
30. Confirm the accountId has been mapped correctly
© 2014 Copyright IBM Corporation
Page 17 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
31. Select Review. In the review section you can review the configuration as well as set specific
actions if an error occurs when the Web Service Invoke Operation is called. For this lab you
will not take any actions if an error is returned.
© 2014 Copyright IBM Corporation
Page 18 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
Build the Accounts API Response
32. Select Response to map the required fields from the AccountService response to the API
response.
33. Select Map Values to see the alternative way to create mappings using the graphical
mapping tool.
© 2014 Copyright IBM Corporation
Page 19 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
34. Click on the connector for the return output field from the Web Service Invoke Operation and
drag and drop it on the connector for the balance field in the API response to map the two
fields. Note that the mapping line is green which indicates that the two fields are compatible
types and the mapping will succeed.
© 2014 Copyright IBM Corporation
Page 20 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
35. The resource implementation is now complete. Click Save API at the top of the editor.
© 2014 Copyright IBM Corporation
Page 21 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
Add the Balance Resource to the Public Plan
In order to be able to test the resource from the integrated test tool you need to first add it to a
plan. In a previous tutorial you created a plan, named Public. It is this plan that you will use to
test the Accounts resource.
36. Select Plans from the navigation pane.
© 2014 Copyright IBM Corporation
Page 22 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
37. Click on the Public Plan name to open the plan editor.
38. Click + Resource.
© 2014 Copyright IBM Corporation
Page 23 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
39. Select Accounts from the list of APIs in the left hand column, then select the Balance
resource. Click Add.
© 2014 Copyright IBM Corporation
Page 24 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
40. You will now have four resources in your Public plan. Click Save.
© 2014 Copyright IBM Corporation
Page 25 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
Test the Balance Resource
The integrated test tool provides the ability to test a resource from the API Manager UI, it is found within
the resource editor in an API.
41. Click APIs in the navigation pane. This will take you to the Draft APIs listing.
© 2014 Copyright IBM Corporation
Page 26 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
42. Click on the Accounts API name to open the API editor.
43. Click the Edit icon next to the Account Balance resource.
© 2014 Copyright IBM Corporation
Page 27 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
44. Click the Test tab.
45. The Test fields should automatically be correctly populated because there is only one
Environment and Plan for this API resource. Enter the parameter value in the table below
and click the Invoke button.
Parameter
Value
accountId
12345
© 2014 Copyright IBM Corporation
Page 28 of 29
Creating a REST API which exposes an existing SOAP Service with IBM API Management 3.0.0.1
46. Confirm that the correct response was returned and a 200 OK response code.
47. There are no rate limits for this resource so you can try testing the API using other
accountIds such as “789” (the balance returned will always be the accountId + 1 in the test
AccountService). Click Parameters to change the input parameter value before clicking
Invoke again.
Summary
In this tutorial, you have learnt:
 How to expose an existing SOAP service as a REST API
This is in a series of tutorials which will cover the features of API Management 3.0. For more
information about this series and other tutorials please see:
http://developer.ibm.com/apimanagement
End of Tutorial
© 2014 Copyright IBM Corporation
Page 29 of 29