Creating a REST API which exposes an existing SOAP Service with IBM API Management

Transcription

1 Creating a REST API which exposes an existing SOAP Service with IBM API Management Page 1 of 29

2 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 Page 2 of 29

3 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 , Creating an assembly REST API with IBM API Management and Creating a SOAP API with IBM API Management tutorials. For more information about this series and other tutorials please see: 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. Page 3 of 29

4 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. Page 4 of 29

5 1. Open a new browser tab and navigate to the URL 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. Page 5 of 29

6 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 Where <managementserver> is the IP Address or hostname of your management server. Page 6 of 29

7 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. Page 7 of 29

8 10. Click APIs in the navigation pane. 11. Click the + REST button to create a new REST API. Page 8 of 29

9 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. Page 9 of 29

10 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. Page 10 of 29

11 16. To create a resource that supports a GET operation, click + Resource. 17. Remove the POST method by clicking the cross. Page 11 of 29

12 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 Page 12 of 29

13 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": } 22. Select the Implementation tab and ensure the Assemble tab is selected. Page 13 of 29

14 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. Page 14 of 29

15 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 Username Leave blank Password Leave blank Page 15 of 29

16 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. Page 16 of 29

17 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 Page 17 of 29

18 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. Page 18 of 29

19 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. Page 19 of 29

20 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. Page 20 of 29

21 35. The resource implementation is now complete. Click Save API at the top of the editor. Page 21 of 29

22 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. Page 22 of 29

23 37. Click on the Public Plan name to open the plan editor. 38. Click + Resource. Page 23 of 29

24 39. Select Accounts from the list of APIs in the left hand column, then select the Balance resource. Click Add. Page 24 of 29

25 40. You will now have four resources in your Public plan. Click Save. Page 25 of 29

26 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. Page 26 of 29

27 42. Click on the Accounts API name to open the API editor. 43. Click the Edit icon next to the Account Balance resource. Page 27 of 29

28 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 Page 28 of 29

29 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: End of Tutorial Page 29 of 29