This tutorial shows you how to define and implement a REST API definition that proxies an
existing service.
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. 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.
- In the Develop screen, click .
- Ensure that OpenAPI 2.0 is selected.
- Select From target service, and click
Next.

- Enter the following information to create a REST API from a target service.
- In the Title field, enter Branches.
- The Name field is auto-populated with
branches.
- Leave the Version field as 1.0.0.
- The Base Path field is auto-populated with
/branches.
- In the Target Service URL field, enter
https://sample-api.us-east-a.apiconnect.automation.ibm.com/bank/branches

- Click Next.
- In the Secure dialog, make sure
- Secure using Client ID
- CORS
are selected and click Next. 
- The new API is created, and the Summary page is displayed. Click
Edit API to continue configuring the API.

- On the Design view, click Definitions in the side
menu bar, and then click Add.

- Enter the following information to create a new definition in the form of an object
Schema.
- In the Schema Name (Key) field enter address.
- In the Type field select object.
- Click Add.
- In the Description field enter The format of the address
object.
- Click Save.
- The schema for new object displays as part of the Design view under the
Definitions section.
- To create properties for the new address object, click Add in the
Properties section.
- To configure the properties, complete the following steps:
- In the Name field enter street1.
- In theType field select string.
- In the Description field add The first line of the
address.
- Click Save.
- The new schema property is created, and is now displayed as part of the
Design view under the Properties section. To complete it,
click the ellipsis icon and select the Details option. Go to the
Documentation tab and add 4660 La Jolla Village Drive
in the Example Value field.
- Click Save.
- Repeat the same process for the other new schema properties by following the information
provided in the 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 schema definitions are presented to developers in the Developer
Portal to provide them with
information about the type of data to expect in their response.
- Click Save.
- Create a second definition schema by clicking Add in the
Definitions pane.
- In the Schema Name (Key) field enter branch.
- In the Type filed select object.
- Click Add.
- In the Description field enter The format of the branch
field.
- Click Save.
- Configure the Properties of the branch object according to Table 2. To
generate new properties click Add, fill in information, then click
Save.
Note: To add and access the Example value of the schema definition you
created, you have to finish the creation process first 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 |
Notice that for the address property, the type
section refers to the definition that you created within your API, and the example is blank. In this
way, you can create complex data structures.

- Click Save.
- On the Design view, select Paths and click the
Plus button to add a new path.
- In the Path name field, enter /details.
- In the Operations section within the Design view,
click the Plus.
- Select get, and then click Add.

- Click Save. The new path called /details appears
in the list of available paths.
- Click /details so you can edit the GET operation
in the Path.
- On the Design view, under
, click
GET.
- Scroll down to the Responses section, and edit the response as follows:
- Leave 200 as the Name (Key).
- Edit the Description field to be 200 OK.
- Click Save.
- In the page banner, click Preferences
.In the Preferences
dialog box, configure the following settings:
- Set Auto-publish to On.
- Set a Target product rate limit.
- Click Edit.
- In the Choose a Rate Limit dialog box, select Custom.
- Set Number of Calls to 5 calls per hour.
- Click Choose Rate Limit.
- In the Preferences dialog box, click Save Preferences.
- Click Save to update the API.
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.
What you did in this tutorial
In this tutorial, you completed the following activities:
- Created a REST API definition.
- Tested the REST API.