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

Add and define a REST API to return the branch details of an example BankA.

To add and define a REST API, complete the following steps:
  1. Log in to API Manager.
  2. In the Welcome page, click the Develop APIs and Products tile.

    API Manager screen

  3. Click Add > API.

    Add API screen

  4. Select From target service. Click Next.

    Select REST API

  5. Enter the appropriate information to create a REST API definition.
    1. In the Title field, enter Branches.
    2. The Name and Base Path fields autopopulate with the terms branches and /branches respectively.
    3. Leave the Version field at 1.0.0.
    4. In the Target Service URL field, enter https://apictutorials.mybluemix.net/branches.

    Basic information screen

  6. Click Next.
  7. In the Security dialog, take the following steps.
    1. Select Limit API calls on a per key basis.
    2. Click Next.

    Security screen

  8. You see the progress as the new API gets created. When it is done, you see a Summary. Click Edit API.

    New API summary

  9. On the Design page, click Definitions in the side bar.
  10. Click Add.

    Definitions page

  11. In the Name field, enter address, and a Description of The format of the address object.
  12. Using the same Definitions panel, configure the Properties definition according to the following table. Create new properties by clicking Add.
    Table 1. Properties
    Property Name Description Type Example
    street1 The first line of the address string 4660 La Jolla Village Drive
    street2 The second line of the address string Suite 300
    city The city of the address string San Diego
    state The state of the address string CA
    zip_code The zip code of the address string 92122

    Address definition

    This is an OpenAPI schema definition and is 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 panel.
  15. Name the definition branch and, in the Description field, enter The format of the branch field.
  16. Configure the branch definition to have the properties listed in the following table by creating new properties and editing the default property. Create new properties by clicking Add .
    Table 2. Properties
    Property Name Description Type Example
    address The address of the branch address  
    type The type of branch string atm
    id The ID of the branch string 9d72ece0-7e7b-11e5-9038-55f9f9c08c06

    Branch definition

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

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

    Paths page

  19. Click Add.
  20. In the Path name field, enter /details.
  21. In the Operations section, click Add.
  22. Select GET and click Add.

    Path info

  23. Click Save.
  24. Click /details in the list of available paths.

    Path list

  25. Click GET in the list of Operations.
  26. Scroll down. In the Response section, click Add.
    1. Enter 200 in the STATUS CODE field.
    2. Select branch in the SCHEMA field.
    3. Enter 200 OK in the DESCRIPTION field.

    Path Response settings

  27. Click Save.

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 Assemble.
  2. Click the Test icon The Test icon.

    Assemble page

  3. On the test Setup pane, click Activate API.

    Test setup

  4. The Test pane refreshes. A Product and Plan are automatically selected.

    Test invoke

  5. Scroll down. Select the get /details Operation.

    Test operation selected

  6. Click Invoke. You may encounter a yellow error box with a URL embedded in it. Click this URL to override a browser certificate error.

    Test invoke

  7. Click Invoke again. The response contains branch data.

    Repeat invoke

What you did in this tutorial

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