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

Complete the following steps to add and define a REST API that returns the branch details of a fictional bank, called BankA.
  1. Log in to the API Manager UI.
  2. On the Home page, click the Develop APIs and products tile.

    API Manager welcome screen

  3. On the Develop page, click Add > API.

    Add API screen

  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://apictutorials.mybluemix.net/branches

    Basic REST API information screen

  7. Click Next.
  8. In the security dialog, select Limit API calls on a per key basis to add a rate limit to the API, and click Next.

    Security 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 to add a new OpenAPI schema definition.

    Definitions page

  11. In the Name field enter address, and in the Description field enter The format of the address object.
  12. Configure the Properties definition according to the following table. Create new properties by clicking Add.
    Table 1. Properties
    PROPERTY NAME PROPERTY TYPE PROPERTY EXAMPLE PROPERTY DESCRIPTION
    street1 string 4660 La Jolla Village Drive The first line of the address
    street2 string Suite 300 The second line of the address
    city string San Diego The city of the address
    state string CA The state of the address
    zip_code string 92122 The zip code of the address

    Address definition

    OpenAPI 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.
  13. Click Save.
  14. Create a second definition by clicking Add in the Definitions pane.
  15. In the Name field enter branch, and in the Description field enter The format of the branch field.
  16. Configure the Properties definition according to the following table. Create new properties by clicking Add.
    Table 2. Properties
    PROPERTY NAME PROPERTY TYPE PROPERTY EXAMPLE PROPERTY DESCRIPTION
    address address   The address of the branch
    type string atm The type of branch
    id string 9d72ece0-7e7b-11e5-9038-55f9f9c08c06 The ID of the branch

    Notice that for the address property, the property type references the definition that you just created within your API, and the example is blank. In this way, you can create complex data structures.

    Branch definition

  17. Click Save.
  18. In the side menu bar, select Paths to display the Paths pane.

    Paths page

  19. Click Add to create a new path.
  20. In the Path name field, enter /details.
  21. In the Operations section, click Add.
  22. Select GET, and then click Add.

    Path info

  23. Click Save. The new path called /details appears in the list of available paths.
  24. Click /details so you can edit the GET operation in the path.
  25. On the Path page, click GET in the Operations section.
  26. Scroll down to the Response section, and edit the response as follows:
    1. Leave 200 as the STATUS CODE.
    2. Change the SCHEMA field to branch.
    3. Edit the DESCRIPTION field to be 200 OK.

    Path Response settings

  27. Click Save.

You successfully created a REST API definition, and you can now test the API.

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. Click the Assemble tab of the branches API, to move to the Assemble view, and then click the Test icon The Test icon.

    Assemble pageNote that the policy for the API is an Invoke policy if you are using the DataPower API Gateway, and is a Proxy policy if you are using the DataPower Gateway (v5 compatible). For more information about policies, see Built-in policies.

    Also note that the test panel is being deprecated, and will be moved to the Test tab in a future release.

  2. On the Test Setup panel, click Activate API. Activating the API creates the default Product and Plan that are needed for the test setup. If your test setup is already configured, you can proceed immediately to the next step.

    Test setup

  3. The Test panel refreshes, and a default Product and Plan are automatically selected.

    Test invoke

  4. In the Operation section, select the get /details operation to invoke.

    Test operation selected

  5. Click Invoke. The API response is displayed in the Response section. If you receive a message relating to an untrusted certificate, click the link provided, accept the certificate, then return to the test environment and click Invoke again.
  6. After the operation has been invoked successfully, the Response section contains the branch details.

    Successful invoke

What you did in this tutorial

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