23
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.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

  • Upload
    others

  • View
    96

  • Download
    0

Embed Size (px)

Citation preview

Page 1: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 2: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 3: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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 studyBank 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 knowsthat 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

Page 4: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

Creating a proxy REST API with IBM API Management 4.0.0.0 April 29, 2015

User rolesIBM 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

Page 5: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 6: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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>/apimanagerWhere <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

Page 7: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 8: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 9: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 10: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 11: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 12: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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 thetable 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

Page 13: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 14: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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. Inthis 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

Page 15: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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 whoare 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

Page 16: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 17: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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 theplan name. Click on Sandbox.

© 2015 Copyright IBM Corporation 17 of 23

Page 18: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 19: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 20: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 21: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 22: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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

Page 23: Creating a proxy REST API with IBM API Management 4.0.0files.meetup.com/19095698/How to create a REST API... · Creating a proxy REST API with IBM API Management 4.0.0.0 April 29,

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