Professional Documents
Culture Documents
TABLE OF CONTENTS
OBJECTIVE....................................................................................................................................3
PREREQUISITES...........................................................................................................................3
CASE STUDY.................................................................................................................................3
USER ROLES.................................................................................................................................4
SUMMARY....................................................................................................................................45
NOTE: This tutorial demonstrates the Google Geocoding API, it is included only as an example.
If you wish to use the Google Geocoding API then you must adhere to the rules and conditions
which are placed on them by Google through their license. See the Google Geocoding API
Documentation (https://developers.google.com/maps/documentation/geocoding/) for more
details.
Objective
In this tutorial, you will learn:
How to assemble calls to multiple REST JSON and XML services
Prerequisites
This tutorial is the second in a series, it builds on the Creating a proxy REST API with IBM API
Management 3.0.0.1 tutorial. It assumes that the Public plan which was constructed as part of
that tutorial is in place.
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 REST 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.
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 document, create and implement a new resource using a combination of
existing RESTful services that locate a branch and retrieve the coordinates for an address in
order to calculate the Google Maps URL for a branch, as shown in the Figure below.
GET /{branchId}/location
GET /xml?address=
IBM API <address>&sensor=false
address, googleMapsLink Management
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:
This tutorial has been written assuming that you are an Administrator or Organization Owner. If
you are 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:
2. Click on the example URI endpoint for the Service titled Branch Location Service (JSON)
to make sure that the location service is operational. This is the service that will be used as
the first step of the assembly. By clicking on the link you are making a REST based GET call
to return the address of a bank branch, the branchId is passed in as a path parameter, valid
branch values are 101, 102, 103.
One of the steps in the assembly you are going to build is going to call out to the Google Geocoding API
(https://developers.google.com/maps/documentation/geocoding/).
3. It is worth checking that the api is available by creating a new tab or window for your browser and
entering the following URL in the location field:
https://maps.googleapis.com/maps/api/geocode/xml?address= 650+Harry+Road,San+Jose,CA,95120-
6099&sensor=false
This will return an xml document containing the response from the Google Geocoding API.
NOTE: Keep the browser tabs open. You will need to access information from them later in the tutorial.
5. Sign in to the IBM API Management platform by clicking entering your credentials and
clicking Sign In.
6. After you sign in, the API Manager Home page is displayed. The home screen displays
activity graphs for each environment.
7. At the top of the screen, the primary banner contains a drop down list for your organizations
and your login name. You must belong to an organization to use the API Manager UI.
combination of existing services, which may also require some transformation or manipulation of
the response that the existing service(s) return.
In the following example, Bank A would like to expose a new API resource which returns the
address and Google Maps URL for a specific branch. For this resource the calling application
will need to provide an identifier for the branch being located. Bank A also appreciates that
customers would like the map URL to be provided with the address so that they do not need to
do a separate search for the address in a map tool.
The resource will be implemented by combining the results of two HTTP GET calls, one that
gets the branch address and one that gets the longitude and latitude for the address which
allows the Google Maps URL to be calculated.
8. Click APIs in the navigation pane. This will take you to the Draft APIs listing.
9. Since this resource is not related to Loans, click the + REST button to create a new REST
API.
10. Populate the fields as shown in the table below. When complete, click the Add button.
11. After creating the Branches API it will immediately appear in the list of available APIs.
14. To create a single location resource that supports a GET operation, click + Resource.
16. Populate the fields as shown in the table below. When complete, click the Add button.
17. Now that the Location resource has been defined, click on the Edit icon to edit the resource
details.
18. Enter a description for the parameter as listed in the table below. All path parameters are
required so the Required checkbox is already selected and is un-editable.
Parameter Description
branchId The unique branch ID
19. Click on the Response Body tab and paste in the sample JSON response for the resource
below. Click somewhere else on the screen and the JSON will be automatically formatted for
you.
{
"address": "650 Harry Road, San Jose, CA 95120, USA",
"googleMapsLink" : "http://maps.google.com/?q=37.2110625,-121.8054238"
}
20. For this resource you will create an assembly of two existing services. Select the
Implementation tab and ensure the Assemble tab is selected.
23. Create a Connection using the values in the table below and click Connect. The URL you
entered will be verified and focus will automatically move to the Define section of the
assembly implementation.
24. Return to the example Branch Location Service (JSON) browser tab or window. This is the
service you entered the URL for in the Connection settings. By opening the example in your
browser you have made a REST based GET call to the service, passing a sample branchId
“101” as a path parameter in the URI.
Copy the JSON response to the clipboard (Type CTRL-A to select the JSON response and
CTRL-C to copy the text)
25. Return to the API Manager browser tab or window. You will be in the DEFINE stage of the
HTTP GET OPERATION task.
26. Click on the Response Body text area and paste the JSON response you just copied (Type
CTRL-V to paste). Click somewhere else on the screen and the JSON will be automatically
formatted for you.
27. Select Configure to map the input parameter of your API to the input parameter of the
HTTP GET Operation
28. Click Select Available Value for the branchId parameter of the HTTP GET Operation.
29. Map the branchId from the API you are creating to the branchId of the HTTP GET Operation
by selecting branchId
31. Select Review. In the 7review section you can review the configuration as well as set
specific actions if an error occurs when the HTTP GET Operation is called. For this lab you
will not take any actions if an error is returned.
34. Create a Connection using the values in the table below and click Connect.
Field Value
Name
Name Google Geocoding API
URL https://maps.googleapis.com/maps/api/geocode/xml?address=
650+Harry+Road,San+Jose,CA,95120-6099&sensor=false
35. Open your browser tab or window which you called the Google Geocoding API from in the
Before You Begin section of this tutorial.
36. Note that the response is in XML format. We will use another feature of the IBM API
Management assembly capability in later steps to map the XML output into the JSON
response for the API resource. Typically the browser will have formatted the XML response
in some way. You need to copy the raw XML. For example, Chrome automatically parses
XML into a document tree, so right-click on the page and select View Page Source.
37. A new browser tab opens with the raw XML output from the service. Copy the XML response
to the clipboard (Type CTRL-A to select the XML response and CTRL-C to copy the text)
38. Return to your API Manager tab. You will be in the DEFINE stage of the HTTP GET
OPERATION 2 task.
39. In the Define stage of the resource implementation, click on the Response Body text area
and paste the XML response you just copied (Type CTRL-V to paste).
40. Select Configure to map the input parameter of your API to the input parameter of the
HTTP GET Operation
41. The sensor parameter has not been exposed externally to consumers of the API, so it will be
defaulted to false for all calls. Click the default value icon next to the sensor parameter,
enter the value false, and then click OK.
42. The default value icon will change to green to indicate that a default value has been set. A
more complex mapping is required to concatenate the response from the branch address
service into the address input parameter for the Google Geocoding API, so click Map Values
to use the graphical tool to map parameters.
43. Click on the connector for the streetAddress value returned from the first HTTP GET
Operation
44. Drag and click the connector for the address input parameter of this task.
45. Click the + icon in the middle of the mapping to apply a mapping function.
46. In this case we require two functions to get an address in the format:
“650+Harry+Road,San+Jose,CA,95120-6099”. First we need to use concatenate to combine
multiple address fields together and then we need to use replace to escape spaces with the
“+” character. To apply multiple functions, select Composite from the list of mapping
functions.
47. Drag and drop the city, state and zipCode fields to the connector on the left side of the
Composite function to add them as input parameters, and then click the edit icon to edit the
function. Note that the mappings are red to indicate that the function configuration is not
complete.
49. The input parameters will be listed in the Source Fields box in the function configuration. In
the Edit Composites box, click the + icon to add a new composite function.
50. Click the Copy function that has been added to change it to another function, and select
Concatenate under the String functions.
51. In the Edit Parameters box for the Concatenate function, enter “,” (comma) as the default
delimiter.
52. In the Edit Composites box, click the + icon to add another new composite function, and this
time change Copy to Replace under the String functions.
53. In the Edit Parameters box for the Replace function, enter “ ” (space) as the original string
and “+” (plus) as the new string. Click Apply.
54. The Composite function configuration is now complete and the mappings have changed to
green.
55. Select Review and note that the latitude and longitude for the address are returned in the
location element of the response from the Google Geocoding API. There is also a field that
returns the complete address that can be used in the API response.
57. Select Map Values because another concatenate function will be required to build the
Google Maps URL from the latitude and longitude.
58. Click on the connector for the formatted_address output field from HTTP GET Operation 2
and map it to the address field in the response. You will probably have to scroll down the
Available values list to see the HTTP GET Operation 2 response.
Note that even though the output of the Google Geocoding API in HTTP GET Operation 2 is
in XML format and the API response is in JSON format, the mapping tool can still be used in
the same method and the data format conversion is done automatically.
a) Map the lat output field from HTTP GET Operation 2 to the googleMapsLink field in the
response
c) Map the lng output field from HTTP GET Operation 2 to the Concatenate function
d) Edit the Concatenate function and set prefix = “http://maps.google.com/?q=” and default
delimiter = “,” (comma)
e) Click Apply and confirm your mapping is updated to reflect the diagram below.
f) Confirm that the Concatenate mapping is yellow due to a type casting warning by
clicking the warning icon on the Response.
g) Confirm that the address mapping is only grey because it is in the background, and
select it to check that it is still green.
60. The resource implementation is now complete. Click Save API at the top of the editor.
62. Click on the Public Plan name to open the plan editor.
64. Select Branches from the list of APIs in the left hand column, then select the Location
resource. Click Add.
65. You will now have two resources in your Public plan. Click Save.
66. Click APIs in the navigation pane. This will take you to the Draft APIs listing.
67. Click on the Branches API name to open the API editor.
70. The Test fields should automatically be correctly populated because there is only one
Environment and Plan in this organization. If you have created additional Environments and
Plans since that tutorial then please ensure Sandbox and Public (Version 1) are selected.
Enter the parameter value in the table below and click the Invoke button.
Parameter Value
branchId 101
71. Confirm that the correct response was returned and a 200 OK response code.
72. You can also try testing the API using the following branchId values: 102 and 103. Click
Parameters to change the input parameter value before clicking Invoke again.
Summary
In this tutorial, you have built on top of the previous tutorial in this series and have learnt:
This is the second 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