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 Copyright IBM Corporation Page 1 of 33

2 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 ADD A WEB SERVICE INVOKE OPERATION TASK...17 BUILD THE ACCOUNTS API RESPONSE ADD THE BALANCE RESOURCE TO THE SANDBOX PLAN TEST THE BALANCE RESOURCE SUMMARY Copyright IBM Corporation Page 2 of 33

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: Copyright IBM Corporation Page 3 of 33

4 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

5 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 Copyright IBM Corporation Page 5 of 33

6 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 Copyright IBM Corporation Page 6 of 33

7 5. Validate that the account service WSDL is displayed Copyright IBM Corporation Page 7 of 33

8 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 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 Copyright IBM Corporation Page 8 of 33

9 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 Copyright IBM Corporation Page 9 of 33

10 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 API Name Path API Description Value Accounts /accounts/v1 Operations related to Bank A accounts 2015 Copyright IBM Corporation Page 10 of 33

11 13. The Accounts API is added to the list of APIs Copyright IBM Corporation Page 11 of 33

12 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 Copyright IBM Corporation Page 12 of 33

13 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 Copyright IBM Corporation Page 13 of 33

14 18. To create a resource that supports a GET operation, click + Resource. 19. Remove the POST method by clicking the cross Copyright IBM Corporation Page 14 of 33

15 20. Populate the fields as shown in the table below. When complete, click the Add button. Field Name Path Display Name Description Value /{accountid}/balance Balance 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 accountid Description Account Identifier 2015 Copyright IBM Corporation Page 15 of 33

16 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": Copyright IBM Corporation Page 16 of 33

17 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 Copyright IBM Corporation Page 17 of 33

18 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 WSDL URL Username Password Value Leave blank Leave blank 2015 Copyright IBM Corporation Page 18 of 33

19 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 Copyright IBM Corporation Page 19 of 33

20 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 Copyright IBM Corporation Page 20 of 33

21 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 Copyright IBM Corporation Page 21 of 33

22 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 Copyright IBM Corporation Page 22 of 33

23 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 Copyright IBM Corporation Page 23 of 33

24 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 Copyright IBM Corporation Page 24 of 33

25 39. The resource implementation is now complete. Click Save at the top of the editor Copyright IBM Corporation Page 25 of 33

26 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 Copyright IBM Corporation Page 26 of 33

27 42. Click + Resource Copyright IBM Corporation Page 27 of 33

28 43. Select Accounts from the list of APIs in the left hand column, then select the Balance resource. Click Add Copyright IBM Corporation Page 28 of 33

29 44. Check that the Balance resource has been added to the plan. Click Save Copyright IBM Corporation Page 29 of 33

30 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 Copyright IBM Corporation Page 30 of 33

31 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 Copyright IBM Corporation Page 31 of 33

32 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 Copyright IBM Corporation Page 32 of 33

33 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: End of Tutorial 2015 Copyright IBM Corporation Page 33 of 33