1. No category

Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
Creating a proxy REST API with
IBM API Management 4.0.0.0
© 2015 Copyright IBM Corporation
1 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
TABLE OF CONTENTS
OBJECTIVE....................................................................................................................................3
CASE STUDY.................................................................................................................................3
USER ROLES.................................................................................................................................3
BEFORE YOU BEGIN....................................................................................................................5
LOG INTO THE API MANAGER....................................................................................................6
CREATE A LOANS REST API.......................................................................................................7
CREATE A LOAN QUOTE PROXY RESOURCE..........................................................................9
CREATE A PLAN......................................................................................................................... 15
TEST THE LOAN QUOTE RESOURCE......................................................................................19
SUMMARY....................................................................................................................................22
© 2015 Copyright IBM Corporation
2 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
Objective
This is the first tutorial in a series which will teach you to use IBM API Management 4.0.0.0 to
create and test a number of different APIs. As this is the first in the series it covers the creation
of a plan which is required for the following tutorials.
In this tutorial you will learn:
 How to create a REST API which proxies an existing REST endpoint
 How to create a Plan and add a Resource to it
 How to test a REST API using the integrated test tool
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 develop the Bank A API Management solution. The solution will include
the documentation and definition of a pure proxy to access the loan quote REST service as
shown in Figure 1 below. This simple proxy allows Bank A to monitor the use of the service and
restrict access to the API.
Figure 1 - Loan Quote REST Proxy
© 2015 Copyright IBM Corporation
3 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
User roles
IBM API Management v4 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. 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.
© 2015 Copyright IBM Corporation
4 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
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 loan quote 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
2. Click on the example URI endpoint for the service titled Loan Service (JSON) to make sure
that the loan quote service is operational. This is the service that you would like to expose
via the API gateway. By clicking on the link you are making a REST based GET call to the
loan quote service, passing the query parameters in the URL.
NOTE: Keep the Loan Service browser tab open for later in the tutorial as you will need some
information from it.
© 2015 Copyright IBM Corporation
5 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
Log into the API Manager
3. Open a new browser tab and navigate to the URL
https://<managementserver>/apimanager
Where <managementserver> is the IP Address or hostname of your management server.
4. Sign in to the IBM API Management platform by entering your credentials and clicking Sign
in.
5. After you sign in, the API Manager Home page is displayed. The home screen displays
activity graphs for the most active APIs and Applications.
6. At the top of the screen, the primary banner contains a drop down list for your organizations
(highlighted in red below) and your login name. You must belong to an organization to use
the API Manager UI.
© 2015 Copyright IBM Corporation
6 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
Create a Loans REST API
Now that you have logged into the API Manager, you can start creating a REST API to expose and
manage Bank A’s loan quote service.
7. Select APIs from the navigation pane. This will take you in to the Draft APIs view, from here
you can compose an API or import a Swagger or WSDL API.
8. Click the + API button and select Compose.
© 2015 Copyright IBM Corporation
7 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
9. Populate the fields as shown in the table below. When complete, click the Add button. This
will add the API to the Draft APIs list.
Field Name
Value
API name
Loans
Path
/loans/v1
API description
Operations related to Bank A loans
Note: The Path specified here will become part of the URL which is eventually called so will
need to be valid for this use.
© 2015 Copyright IBM Corporation
8 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
Create a Loan Quote Proxy Resource
10. Click on the Loans link to define the specific resources that are available for the API.
11. Review the Loans REST API Security configuration, Click Security.
© 2015 Copyright IBM Corporation
9 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
12. 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.
13. Switch to the Resources configuration panel. Click Resources.
14. To create a single quote resource that supports a GET operation, click + Resource.
© 2015 Copyright IBM Corporation
10 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
15. By default, the HTTP methods GET and POST are displayed. Remove the POST method by
clicking the X inside of the Post button
16. Populate the fields as shown in the table below. Check that Identification is selected for
this resource. When complete, click the Add button.
Field Name
Value
Path
/quote?loanAmount=20000&annualInterestRate=0.9&termInMonths=52
Display
Name
Quote
Description
Loan quote
17. Now that the quote resource has been defined, click on the Edit icon to edit the resource
details.
© 2015 Copyright IBM Corporation
11 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
18. The query parameters from the Path you supplied are listed in the Parameters panel. Select
the Required check box for each parameter and enter a description for each one as listed in the
table below.
Parameter
Description
loanAmount
Total loan amount
annualInterestRate
Annual interest rate (%)
termInMonths
Duration of the loan (in months)
19. In this resource we don't need to add any Request headers so the next step is to add a
Response body. In order to fill this in we need to call the endpoint in a browser, as was done
in the Before You Begin section of this tutorial.
To retrieve the details of the quote status service to use in the resource definition, select the
Bank A browser tab or go to the following URL in a different browser tab or window:
http://banka.mybluemix.net/loans/v1/quote?
loanAmount=20000&annualInterestRate=0.9&termInMonths=52
20. Copy the JSON response to the clipboard (Type CTRL-A to select the JSON response and
CTRL-C to copy the text)
21. Switch back to the API Manager tab or window.
© 2015 Copyright IBM Corporation
12 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
22. Click on the Response body tab. A response is generated for you with the standard return
code for a GET request of 200 OK . Click on the + button to the right of the response to edit
this response.
© 2015 Copyright IBM Corporation
13 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 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.
24. For this resource you will simply proxy the existing service. Select the Implementation tab
and click the Proxy button
© 2015 Copyright IBM Corporation
14 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
25. Add the following endpoint URL to the PROXY URL field.
Endpoint URL
http://banka.mybluemix.net/loans/v1/quote
Note: This is the same URL as used to invoke the Quote service, but without the query
parameters.
26. Click Save API at the top of the API editor.
You have now defined your first REST API. The example response text will help developers who
are creating applications and integrating with the Bank A Loan API for the first time. The
example is also used by the API Manager to configure the proxy itself so no coding is required.
Before you can test the resource from within the API Manager UI you will need to add it to a
Plan.
© 2015 Copyright IBM Corporation
15 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
Create a Plan
You have now defined and documented the API for the loan quote service. The next step is to
create a plan so that you can test your API.
27. Select Plans from the navigation pane.
28. A plan is a packaging construct by which APIs are made available to consumers. A plan
makes available a collection of resources from one or more APIs, and is published to
developer organizations. An application developer, who belongs to the relevant developer
organization, can gain access to APIs by registering their applications to access plans. A
plan carries with it a collection of policy settings. In its simplest form, a plan defines a single
quota policy that applies to all the API resources that are accessed through the plan. For the
current purpose we are creating a plan for testing the API from the integrated test tool within
the API Manager UI, it will not be used to publish the API externally so we will name the plan
accordingly.
Click + Plan to create a new plan.
© 2015 Copyright IBM Corporation
16 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
29. Populate the fields as shown in the table below. When complete, click the Add button.
Field Name
Value
Plan Name
Sandbox
Plan Description
Plan used for testing APIs while they are
being developed.
30. Sandbox will immediately appear in the list of Plans. To edit the plan you need to click on the
plan name. Click on Sandbox.
© 2015 Copyright IBM Corporation
17 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
31. In order to expose the resource you have created you need to add it to the Public plan.
Click + Resource
32. Ensure that Loans is the selected API in the left hand column, then select the Quote
resource you previously created. Click Add.
© 2015 Copyright IBM Corporation
18 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
33. The resource is added to the Sandbox plan. If required, you can set rate limits for the
resource or plan as a whole from this editor. At the moment you are going to leave these as
unlimited but you will be setting rate limits in a later tutorial. You now have the resource
added to the plan so you can save the plan and test your resource.
Click Save
© 2015 Copyright IBM Corporation
19 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
Test the Loan Quote Resource
The API Manager UI contains an integrated test tool which allows an API Developer to invoke APIs
deployed within a plan deployed to a given environment. You have just created the Sandbox plan and
added your resource to it. API Management creates a Sandbox environment for your organization; it is
this which we are going to use for testing the resource.
34. To test your REST resource to ensure that it is defined and implemented correctly, select
APIs from the navigation pane.
35. To edit the API you need to click on the name. Click on Loans.
© 2015 Copyright IBM Corporation
20 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
36. Click the Edit icon for the GET quote resource.
37. Click the Test tab.
© 2015 Copyright IBM Corporation
21 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
38. The Environment and Plan fields should automatically be correctly populated because there
is only one of each in your organization, however, if you are working in an organization
where this isn't the case select the Sandbox environment and the Sandbox (Version 1)
plan.
Enter the parameter values in the table below and click the Invoke button.
Parameter
Value
loanAmount
10000
annualInterestRate
1.5
termInMonths
36
39. Confirm that the correct response was returned and a 200 response code.
© 2015 Copyright IBM Corporation
22 of 23
Creating a proxy REST API with IBM API Management 4.0.0.0
April 29, 2015
Summary
In this tutorial you have seen:



How to create a REST API which proxies an existing REST endpoint
How to create a Plan and add a resource to it
How to test a REST API using the integrated test tool
This is the first in a series of tutorials which will cover the features of API Management 4.0.0.0.
For more information about this series and other tutorials please see:
http://developer.ibm.com/apimanagement
End of Tutorial
© 2015 Copyright IBM Corporation
23 of 23