Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
Creating an assembly REST API with
IBM API Management 4.0.0.0
© 2015 Copyright IBM Corporation
Page 1 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
TABLE OF CONTENTS
OBJECTIVE....................................................................................................................................3
PREREQUISITES...........................................................................................................................3
CASE STUDY.................................................................................................................................4
USER ROLES.................................................................................................................................4
BEFORE YOU BEGIN....................................................................................................................5
LOG INTO THE API MANAGER....................................................................................................6
CREATE A BRANCHES REST API............................................................................................... 7
CREATE A BRANCH LOCATION ASSEMBLY RESOURCE......................................................12
ADD A BRANCH ADDRESS HTTP GET OPERATION TASK ....................................................18
ADD A GOOGLE GEOCODE API HTTP GET OPERATION TASK............................................23
BUILD THE BRANCHES API RESPONSE................................................................................. 38
ADD THE BRANCH LOCATION RESOURCE TO SANDBOX PLAN ........................................44
TEST THE BRANCH LOCATION RESOURCE...........................................................................47
SUMMARY....................................................................................................................................50
© 2015 Copyright IBM Corporation
Page 2 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
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 4.0.0.0 tutorial. It assumes that the Sandbox 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
© 2015 Copyright IBM Corporation
Page 3 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
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.
Figure - Branch Locator REST Assembly
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
This tutorial has been written assuming that you are an Administrator or Organization Owner.
Before you begin
It is assumed that the Exposing a proxy REST API with IBM API Management 4.0.0.0 tutorial
has been completed before starting the steps provided here. See Prerequisites section for
more details.
© 2015 Copyright IBM Corporation
Page 4 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
Access the Bank A Backend Service
Verify that the backend applications are available. Remember that the goal is to expose these
services 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
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.
Access the Google Geocode api
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
© 2015 Copyright IBM Corporation
Page 5 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
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.
Log into the API Manager
4. Open a new browser tab navigate to the URL https://<managementserver>/apimanager
Where <managementserver> is the IP Address or hostname of your management server
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.
© 2015 Copyright IBM Corporation
Page 6 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
Create a Branches REST API
In the first tutorial in this series, Creating a proxy REST API with IBM API Management
4.0.0.0, you created a simple REST proxy of an existing API. A proxy REST API allows you to
control access to, monitor the use of, and enforce rate limits on an existing API. While there are
times when a proxy API may suffice it is often the case that you don’t have an existing API that
exactly matches your requirements and you would like to expose a new API. This may be a
combination of existing APIs, which may also require some transformation or manipulation of the
response that the existing API(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.
© 2015 Copyright IBM Corporation
Page 7 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
9. Since this resource is not related to Loans, Click the + API button and select Compose to
create a new API.
10. Populate the fields as shown in the table below. When complete, click the Add button.
Field Name
Value
API Name
Branches
API Context
/branches/v1
API Description
Operations related to Bank A branches
© 2015 Copyright IBM Corporation
Page 8 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
11. After creating the Branches API it will immediately appear in the list of available APIs.
Create a Branch Location Assembly Resource
12. Click the Branches API link to define the specific resources that are available for it.
© 2015 Copyright IBM Corporation
Page 9 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
13. Review the Loans REST API Security configuration, Click Security.
14. 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.
© 2015 Copyright IBM Corporation
Page 10 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
15. Switch to the Resources configuration panel. Click Resources.
16. To create a single location resource that supports a GET operation, click + Resource.
17. Remove the POST method by clicking the cross.
© 2015 Copyright IBM Corporation
Page 11 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
18. Populate the fields as shown in the table below. When complete, click the Add button.
Field Name
Value
Path
/{branchId}/location
Display Name
Location
Description
Branch Address and Google Maps URL
19. Now that the Location resource has been defined, click on the Edit icon to edit the resource
details.
© 2015 Copyright IBM Corporation
Page 12 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
20. 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
21. 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.
22. Copy the JSON response below (Type CTRL-C).
{
"address": "650 Harry Road, San Jose, CA 95120, USA",
"googleMapsLink" : "http://maps.google.com/?q=37.2110625,-121.8054238 "
}
© 2015 Copyright IBM Corporation
Page 13 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
23. Paste the JSON response you just copied (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.
© 2015 Copyright IBM Corporation
Page 14 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
24. For this resource you will create an assembly of two existing services. Select the
Implementation tab and ensure the Assemble tab is selected.
Add a Branch Address HTTP GET Operation Task
25. Click the + icon to add a task to the resource implementation, and select the GET Operation
in the HTTP section.
© 2015 Copyright IBM Corporation
Page 15 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
26. 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.
Field
Value
Name
Branch Address Service
URL
http://banka.mybluemix.net/branches/v1/{branchId}/location
27. 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)
28. Return to the API Manager browser tab or window. You will be in the DEFINE stage of the
HTTP GET OPERATION task.
© 2015 Copyright IBM Corporation
Page 16 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
29. 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.
30. Select CONFIGURE to map the input parameter of your API to the input parameter of the
HTTP GET Operation
31. Click Select Available Value for the branchId parameter of the HTTP GET Operation.
© 2015 Copyright IBM Corporation
Page 17 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
32. Map the branchId from the API you are creating to the branchId of the HTTP GET Operation
by selecting branchId
33. Confirm the branchId has been mapped correctly
34. Select REVIEW. In the Review 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 tutorial
you will not take any actions if an error is returned.
© 2015 Copyright IBM Corporation
Page 18 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
Add a Google Geocode API HTTP GET Operation Task
35. Click the + icon to add another task to the assembly implementation, and select GET
Operation from the HTTP section.
36. Create a Connection using the values in the table below and click Connect.
Field
Name
Value
Name
Google Geocoding API
URL
https://maps.googleapis.com/maps/api/geocode/xml?address=
650+Harry+Road,San+Jose,CA,95120-6099&sensor=false
NOTE: please check that copy and paste of this url hasn't picked up extra line feed characters
where the text has wrapped. There should be no spaces in the URL. If in doubt please try the
URL in a browser you should get a successful response populated with information about the
address provided. (see the Before You Begin section of this tutorial.)
© 2015 Copyright IBM Corporation
Page 19 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
37. Open your browser tab or window which you called the Google Geocoding API from in the
Before You Begin section of this tutorial.
© 2015 Copyright IBM Corporation
Page 20 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
38. 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.
39. 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)
40. Return to your API Manager tab. You will be in the DEFINE stage of the HTTP GET
OPERATION 2 task.
© 2015 Copyright IBM Corporation
Page 21 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
41. 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).
42. Select Configure to map the input parameter of your API to the input parameter of the
HTTP GET Operation
© 2015 Copyright IBM Corporation
Page 22 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
43. 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.
44. 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.
© 2015 Copyright IBM Corporation
Page 23 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
45. Click on the connector for the streetAddress value returned from the first HTTP GET
Operation
46. Drag and click the connector for the address input parameter of this task.
© 2015 Copyright IBM Corporation
Page 24 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
47. Click the + icon in the middle of the mapping to apply a mapping function.
48. 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.
© 2015 Copyright IBM Corporation
Page 25 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
49. 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. Note that the mappings are red to
indicate that the function configuration is not complete.
50. Click the edit icon on the Composite function.
© 2015 Copyright IBM Corporation
Page 26 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
51. 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.
52. Click the Copy function that has been added to change it to another function, and select
Concatenate under the String functions.
© 2015 Copyright IBM Corporation
Page 27 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
53. In the Edit Parameters box for the Concatenate function, enter “,” (comma) as the default
delimiter.
54. 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.
© 2015 Copyright IBM Corporation
Page 28 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
55. In the Edit Parameters box for the Replace function, enter “ ” (space) as the original string
and “+” (plus) as the new string. Click Apply.
56. The Composite function configuration is now complete and the mappings have changed to
green.
© 2015 Copyright IBM Corporation
Page 29 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
57. 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.
© 2015 Copyright IBM Corporation
Page 30 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
Build the Branches API Response
58. Select Response to map the required fields from the Google Geocoding API response to the
response of the resource you are building for your Branches API.
59. Select Map Values because another concatenate function will be required to build the
Google Maps URL from the latitude and longitude.
© 2015 Copyright IBM Corporation
Page 31 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
60. 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.
© 2015 Copyright IBM Corporation
Page 32 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
61. Create a googleMapsLink in the format “http://maps.google.com/?q=37.2110625,121.8054238” using the following steps:
a)
Map the lat output field from HTTP GET Operation 2 to the googleMapsLink field in the
response
b)
Add a Concatenate function to the mapping
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)
© 2015 Copyright IBM Corporation
Page 33 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
e)
f)
April 30, 2015
Click Apply and confirm your mapping is updated to reflect the diagram below.
Confirm that the Concatenate mapping is yellow due to a type casting warning by
clicking the warning icon on the Response.
© 2015 Copyright IBM Corporation
Page 34 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
g)
April 30, 2015
Confirm that the address mapping is only grey because it is in the background, and
select it to check that it is still green.
© 2015 Copyright IBM Corporation
Page 35 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
62. The resource implementation is now complete. Click Save API at the top of the editor.
© 2015 Copyright IBM Corporation
Page 36 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
Add the Branch Location Resource to 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 the previous tutorial you created a plan, named Sandbox. It is this plan that you will use
to test the Branch Location resource.
63. Select Plans from the navigation pane.
64. Click on Sandbox to open the plan editor.
© 2015 Copyright IBM Corporation
Page 37 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
65. Click + Resource.
66. Select Branches from the list of APIs in the left hand column, then select the Location
resource. Click Add.
© 2015 Copyright IBM Corporation
Page 38 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
67. You will now have two resources in the Sandbox plan. Click Save.
© 2015 Copyright IBM Corporation
Page 39 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
Test the Branch Location 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.
68. Click APIs in the navigation pane. This will take you to the APIs listing.
69. Click on the Branches API name to open the API editor.
© 2015 Copyright IBM Corporation
Page 40 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
70. Click the edit icon for the Location resource.
71. Click the Test tab.
72. 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 Sandbox (Version 1) are selected.
Enter the parameter value in the table below and click the Invoke button.
Parameter
Value
branchId
101
© 2015 Copyright IBM Corporation
Page 41 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
73. Confirm that the correct response was returned with a 200 OK response code
74. 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.
© 2015 Copyright IBM Corporation
Page 42 of 43
Creating an assembly REST API with IBM API Management 4.0.0.0
April 30, 2015
Summary
In this tutorial, you have built on top of the previous tutorial in this series and have learnt:

How to assemble calls to multiple REST JSON and XML services
This is the second 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 43 of 43