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:
  1. Creating a REST API definition
  2. Testing the REST API

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.
  1. Log in to API Manager.
  2. On the Home page, in the left panel, either click the Develop icon, or click the Develop APIs and products tile.
  3. In the Develop screen, click Add > API.
  4. Ensure that OpenAPI 2.0 is selected.
  5. Select From target service, and click Next.

    From target service screen

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

    Basic REST API information screen

  7. Click Next.
  8. In the Secure dialog, make sure
    • Secure using Client ID
    • CORS
    are selected and click Next.

    Secure screen

  9. The new API is created, and the Summary page is displayed. Click Edit API to continue configuring the API.

    New API summary

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

    Definitions page

  11. Enter the following information to create a new definition in the form of an object Schema.
    1. In the Schema Name (Key) field enter address.
    2. In the Type field select object.
    3. Click Add.
    4. In the Description field enter The format of the address object.
  12. Click Save.
  13. The schema for new object displays as part of the Design view under the Definitions section.
  14. To create properties for the new address object, click Add in the Properties section.
  15. To configure the properties, complete the following steps:
    1. In the Name field enter street1.
    2. In theType field select string.
    3. In the Description field add The first line of the address.
    4. Click Save.
    5. 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.
    6. Click Save.
  16. 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

    Address definition

    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.
  17. Click Save.
  18. Create a second definition schema by clicking Add in the Definitions pane.
    1. In the Schema Name (Key) field enter branch.
    2. In the Type filed select object.
    3. Click Add.
    4. In the Description field enter The format of the branch field.
    5. Click Save.
  19. 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.

    Branch definition

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

    Path info

  25. Click Save. The new path called /details appears in the list of available paths.
  26. Click /details so you can edit the GET operation in the Path.
  27. On the Design view, under Paths > Operations, click GET.
  28. Scroll down to the Responses section, and edit the response as follows:
    1. Leave 200 as the Name (Key).
    2. Edit the Description field to be 200 OK.
  29. Click Save.
  30. In the page banner, click Preferences settings button.
    In the Preferences dialog box, configure the following settings:
    1. Set Auto-publish to On.
    2. Set a Target product rate limit.
      1. Click Edit.
      2. In the Choose a Rate Limit dialog box, select Custom.
      3. Set Number of Calls to 5 calls per hour.
      4. Click Choose Rate Limit.
    3. In the Preferences dialog box, click Save Preferences.
  31. 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.
To test the REST API, complete the following steps.
  1. On the Develop page, click the API to edit it.
  2. Click the Test tab.
  3. In the Test page's banner, verify that the API is set to "Online". Test tab
  4. Click Send in the Request section to execute an API call, which tests the API. The response displays the status code that you defined (200) and the bank branch data that the API retrieved.Response page
  5. 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.Body tab

What you did in this tutorial

In this tutorial, you completed the following activities:
  • Created a REST API definition.
  • Tested the REST API.