1. No category

Creating a REST API which exposes an existing SOAP Service with IBM API Management
Creating a REST API which exposes
an existing SOAP Service with
IBM API Management 4.0.0.0
© 2015 Copyright IBM Corporation
Page 1 of 33
April 30, 2015
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
TABLE OF CONTENTS
OBJECTIVE....................................................................................................................................3
PREREQUISITES...........................................................................................................................3
CASE STUDY.................................................................................................................................4
USER ROLES.................................................................................................................................5
BEFORE YOU BEGIN....................................................................................................................5
LOG INTO THE API MANAGER....................................................................................................8
CREATE AN ACCOUNTS REST API............................................................................................ 9
CREATE A BALANCE ASSEMBLY RESOURCE....................................................................... 12
ADD A WEB SERVICE INVOKE OPERATION TASK.................................................................17
BUILD THE ACCOUNTS API RESPONSE................................................................................. 22
ADD THE BALANCE RESOURCE TO THE SANDBOX PLAN ................................................. 25
TEST THE BALANCE RESOURCE............................................................................................ 29
SUMMARY....................................................................................................................................31
© 2015 Copyright IBM Corporation
Page 2 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
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 4.0.0.0, Creating an assembly REST API with IBM API Management 4.0.00
and Creating a SOAP API with IBM API Management 4.0.0.0 tutorials.
For more information about this series and other tutorials please see:
http://developer.ibm.com/apimanagement
© 2015 Copyright IBM Corporation
Page 3 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
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.
Figure 1 – Balance Enquiry SOAP to REST Conversion
© 2015 Copyright IBM Corporation
Page 4 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
User roles
IBM API Management 4 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.
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.
1. Open a new browser tab and navigate to the URL
http://banka.mybluemix.net/home/index.html
© 2015 Copyright IBM Corporation
Page 5 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
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.
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.
© 2015 Copyright IBM Corporation
Page 6 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
5. Validate that the account service WSDL is displayed.
© 2015 Copyright IBM Corporation
Page 7 of 33
April 30, 2015
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
Log into the API Manager
To save time, and for the purpose of this tutorial, 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.
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.
© 2015 Copyright IBM Corporation
Page 8 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
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.
10. Click APIs in the navigation pane.
© 2015 Copyright IBM Corporation
Page 9 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
11. Click the + API button and select Compose to create a new API.
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
© 2015 Copyright IBM Corporation
Page 10 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
13. The Accounts API is added to the list of APIs.
© 2015 Copyright IBM Corporation
Page 11 of 33
April 30, 2015
Creating a REST API which exposes an existing SOAP Service with IBM API Management
Create a Balance Assembly Resource
14. Click on the Accounts API name to enter the API editor.
15. Review the Loans REST API Security configuration, Click Security.
© 2015 Copyright IBM Corporation
Page 12 of 33
April 30, 2015
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
16. The API identification and authentication requirements are displayed beneath the titles
"Identify Application Using" and "Authenticate Application Users Using". You can also upload
or link to external documentation for the API.
Check that Identify Application Using is set to Client ID.
17. Switch to the Resources configuration panel. Click Resources.
© 2015 Copyright IBM Corporation
Page 13 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
18. To create a resource that supports a GET operation, click + Resource.
19. Remove the POST method by clicking the cross.
© 2015 Copyright IBM Corporation
Page 14 of 33
April 30, 2015
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
20. 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
21. Now that the balance resource has been defined, click on the Edit icon to edit the resource
details.
22. 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
© 2015 Copyright IBM Corporation
Page 15 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
23. Click on the Response body tab. A response is generated for you with the standard
response for a GET request of 200 OK . Click on the + button to the right of the response to
edit this response.
24. Paste the JSON response below (Type CTRL-V to paste) into the Response Body. Click
somewhere else on the screen and the JSON will be automatically formatted for you. In this
tutorial we are providing a sample response body for the documentation. It is possible to also
provide a JSON schema for the responses should you wish to. In this case we will just use
the default value.
{
"balance": 1234.56
}
© 2015 Copyright IBM Corporation
Page 16 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
25. Select the Implementation tab and ensure the Assemble tab is selected.
Add a Web Service Invoke Operation Task
26. 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.
© 2015 Copyright IBM Corporation
Page 17 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
27. You are now on the CONNECT tab for the assembly task. 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://banka.mybluemix.net/services/AccountService?wsdl
Username
Leave blank
Password
Leave blank
© 2015 Copyright IBM Corporation
Page 18 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
28. 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.
29. Click the DEFINE tab. This is where you can any headers if you wish. You do not need to
add anything on this tab for this tutorial.
© 2015 Copyright IBM Corporation
Page 19 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
30. Select CONFIGURE to map the input parameter of your API to the input parameter of the
Web Service Invoke Operation.
31. Click Select Available Value for the arg0 parameter of the Web Service Invoke Operation.
32. Map the accountId from the API you are creating to the arg0 of the Web Service Invoke
Operation by selecting accountId.
© 2015 Copyright IBM Corporation
Page 20 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
33. Confirm the accountId has been mapped correctly
34. Select ENDPOINT. Here you can overwrite the endpoint from the WSDL. You do not need to
change the endpoint for this tutorial.
© 2015 Copyright IBM Corporation
Page 21 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
35. 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 tutorial
you will not take any actions if an error is returned.
© 2015 Copyright IBM Corporation
Page 22 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
Build the Accounts API Response
36. Select Response to map the required fields from the AccountService response to the API
response.
37. As in the overview Response a standard 200 return code is preselected for you. Select Map
Values to see the alternative way to create mappings using the graphical mapping tool.
© 2015 Copyright IBM Corporation
Page 23 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
38. 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.
© 2015 Copyright IBM Corporation
Page 24 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
39. The resource implementation is now complete. Click Save at the top of the editor.
© 2015 Copyright IBM Corporation
Page 25 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
Add the Balance Resource to the Sandbox 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 Sandbox. It is this plan that you will use to
test the Accounts resource.
40. Select Plans from the navigation pane.
41. Click on the Sandbox Plan name to open the plan editor.
© 2015 Copyright IBM Corporation
Page 26 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
42. Click + Resource.
© 2015 Copyright IBM Corporation
Page 27 of 33
April 30, 2015
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
43. Select Accounts from the list of APIs in the left hand column, then select the Balance
resource. Click Add.
© 2015 Copyright IBM Corporation
Page 28 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
44. Check that the Balance resource has been added to the plan. Click Save.
© 2015 Copyright IBM Corporation
Page 29 of 33
April 30, 2015
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
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.
45. Click APIs in the navigation pane. This will take you to the Draft APIs listing.
46. Click on the Accounts API name to open the API editor.
© 2015 Copyright IBM Corporation
Page 30 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
47. Click the Edit icon next to the Account Balance resource.
48. Click the Test tab.
49. 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
© 2015 Copyright IBM Corporation
Page 31 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
50. Confirm that the correct response was returned with 200 OK response code.
51. 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.
© 2015 Copyright IBM Corporation
Page 32 of 33
Creating a REST API which exposes an existing SOAP Service with IBM API Management
April 30, 2015
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 4.0. For more
information about this series and other tutorials please see:
http://developer.ibm.com/apimanagement
End of Tutorial
© 2015 Copyright IBM Corporation
Page 33 of 33