Tutorial: Creating a proxy REST API definition

This tutorial shows you how to define and implement a REST API definition that proxies an existing service.

About this tutorial

In this tutorial you will complete the following lessons:

Before you begin

Note: The Sandbox catalog must be configured to use either a DataPower® API Gateway, or a DataPower Gateway (v5 compatible), or both. For detailed information, see Creating and configuring Catalogs.

Creating a REST API definition

You can create and define a REST API that returns the branch details of a fictional bank, called BankA by using the following steps.

Log in to API Manager.
On the Home page, in the left panel, either click the Develop icon, or click the Develop APIs and products tile as depicted in the following image.
In the Develop screen, click Add > API.
In the OpenAPI 2.0 screen, select the OpenAPI 2.0 tab.
Note: By default, the OpenAPI 2.0 tab is selected.
Under the Create section, select the From target service radio button.
Click Next.
In the Create API from target service screen, under the Info section, enter the following values to create a REST API from a target service.
1. In the Title field, enter Branches.
  Note: The Name field is auto-populated with the value that you have entered in the Title field. In this case, the Name field is auto-populated with branches.
2. Leave the Version field as 1.0.0.
  The Base path field is auto-populated with /branches.
3. In the Target service URL field, enter https://sample-api.us-east-a.apiconnect.automation.ibm.com/bank/branches
4. Click Next.
Under the Secure section,
1. Select the Secure using Client ID and CORS check boxes, if not already selected.
2. Click Next.
Under the Summary section,
1. Ensure that Generated OpenAPI 2.0 definition and Applied security marked with green color ticks.
  The green color ticks depict successful API creation.
2. Click Edit API to continue configuring the API.
In the new screen, select the Design tab, if not already selected.
In the left panel of the Design view screen, click the + icon adjacent toDefinitions.
In the Add schema dialog box,
1. In the Schema Name (Key) field enter address.
2. From the Type drop-down list, select object.
3. Click Add.
  The Add schema dialog box is now closed. In the right panel of the Design view screen, the address section is displayed.
4. Under the address section, in the Description field, enter The format of the address object.
5. In the top right corner, click Save.
The schema for new object, address, is now displayed under the Definitions section.
To create properties for the new object, address,
1. Under the Definitions section, select address.
  The address section is displayed in the right panel.
2. Under the address section, click Add.
  The Add new property dialog box is displayed.
To configure the properties, in the Add new property dialog box, enter the following values.
1. In the Name field, enter street1.
2. From theType drop-down list, select string.
3. In the Description field, add The first line of the address.
4. Click Save.
  The new schema property is created, and is displayed in Definitions > address > Properties.
5. To complete the properties configuration, click the Options icon (three dots) adjacent to street1 and then select Details.
  The View details for street1dialog box is displayed.
6. In the View details for street1dialog box, perform the following steps.
  1. Click the Documentation tab.
  2. In the Example Value field, enter 4660 La Jolla Village Drive.
  3. Click Save.

To create other new schema properties, repeat Step 14 and enter the values provided in Table 1.

Table 1. Address properties
SCHEMA NAME (KEY)	TYPE	DESCRIPTION	EXAMPLE VALUE
`street2`	`string`	`The second line of the address`	`Suite 300`
`city`	`string`	`The city of the address`	`San Diego`
`state`	`string`	`The state of the address`	`CA`
`zip_code`	`string`	`The zip code of the address`	`92122`

Note: The developers can find the schema definitions in the Developer Portal. These schema definitions contain information about the type of data that developers expect in their responses.

To create a second definition schema, repeat Step 11 to Step 12.
For example, create a new definition schema named branch.

To configure properties of branch, repeat Step 13 to Step 14 and enter the values provided in Table 2.

Note: To add and access the Example value of the schema definition you created, you must complete the process by clicking Save.

Table 2. Branch properties
SCHEMA NAME (KEY)	TYPE	DESCRIPTION	EXAMPLE VALUE
`address`	`address`	`The address of the branch`
`type`	`string`	`The type of branch`	`atm`
`id`	`string`	`The ID of the branch`	`9d72ece0-7e7b-11e5-9038-55f9f9c08c06`

Note that, for the address property, the type section refers to the definition that you created within your API, and the example section is blank. Following this process, you can create complex data structures.

Branch definition

To add a new path, in the left panel of the Design view screen, click the + icon adjacent to Paths.
In the Add schema dialog box, perform the following steps.
1. In the Path field, enter /details.
2. Click Add.
The new path called /details appears in the list of available paths.
In Paths > /details, click the + icon adjacent to Operations
In the Add schema dialog box, perform the following steps.
1. From the Verb drop-down list, select get.
2. Click Add.
The GET section is displayed in the right panel of the Design view screen.
Click Save in the right panel of the Design view screen.
To edit the GET operation in the Path, click /details.
To edit the GET operation in the Path, in the left panel of the Design view screen, under Paths > Operations, click GET.
In the right panel, in the GET section, scroll down to the Responses section.
To edit the response, perform the following steps.
1. Click the Options icon (three dots) adjacent to 200 and then select Edit.
  A section named 200 is displayed in the right panel of the Design screen.
2. Under the 200 section, perform the following steps.
  1. In the Name (Key) field, enter 200.
  2. In the Description field, enter 200 OK.
  3. Click Save.

Now the API is online and available for use, so you can test it.

Testing the REST API

Note: Due to Cross-Origin Resource Sharing (CORS) restrictions, the assembly test tool cannot be used with the Chrome or Safari browsers on the macOS Catalina platform.

Before you begin

Configure the gateway service before testing the REST API.

To test the REST API, complete the following steps.

On the Develop page, click the Menu icon (three dots), adjacent to the API, and then click Edit API.
Click the Test tab.
Click Target Configuration.
The Preferences dialog box is displayed.
In the Preferences dialog box, perform the following tasks.
1. Set the Auto-publish option to On.
2. To set a Target product rate limit, perform the following tasks.
  1. Click Edit.
  2. In the Choose a Rate Limit dialog box, select the Custom radio button.
  3. In the Number of Calls text box, enter 5.
  4. From the Per drop-down list, select hour.
  5. Click Choose Rate Limit.
3. In the Preferences dialog box, click Save Preferences.
Click Develop on the top of the page.
On the Develop page, click the Menu icon (three dots), adjacent to the API that you want to edit, and then click Edit API.
Click the Test tab.
In the Test page's banner, ensure that the API is set to Online.
To execute an API call, under the Request section, click Send.
This tests the API. The response displays the status code that you defined (200) and the bank branch data that the API retrieved.
Click Send at least 5 more times so that you exceed the defined rate limit. Now the response returns the status code 429 "Too many requests" to indicate that you exceeded the rate limit.

What you did in this tutorial

In this tutorial, you completed the following activities:

Created a REST API definition.
Tested the REST API.