This tutorial was written based on API Management V4, which has been superseded by API Connect.

If you are interested in pushing a REST API to API Connect, see the tutorial Pushing a REST API from IBM Integration Bus V10 into IBM API Connect.

You might also be interested in the following resources:

If you have have created and deployed a REST API in the Integration Toolkit of IBM Integration Bus V10, you can click a button to push the API to IBM API Management V4. This uses the Swagger file for the REST API to register the API with IBM API Management, without you needing to do anything else. You can then use IBM API Management to perform the following tasks:

  • Promote and monitor the usage of the REST API.
  • Secure and authenticate access requests from external users and applications to the REST service running on your IBM Integration Bus.

Overview

This step-by-step guide shows you how easily you can push a REST API from the Integration Toolkit to IBM API Management on Cloud, for the following scenario.

Scenario
Diagram of scenario for REST API in Integration Toolkit, deployed to IIB on Cloud, and its Swagger file pushed to API Management

Scenario diagram notes:

[1] A free trial account for API Management on Cloud was registered, and the tutorial Create and Test a Proxy REST API used to test API Management … and create a sandbox Plan. (This enables the REST API to be tested and used in the Cloud, without needing to set up the infrastructure for a local API Management environment.)
(See API Management on Cloud in the IBM Cloud Shop. Alternatively, you can use a trial with API Management on Bluemix.)

[2] A free trial account for IBM Integration Bus on Cloud (IIB on Cloud) was registered, and the sample CustomerDatabaseV1 integration (REST API) used to test IIB on Cloud. (This enables the REST API to be tested and used in the Cloud, without needing to set up access through the company firewall to the CustomerDatabaseV1 REST API deployed on a local integration server.) Access to IIB on Cloud is secured by basic authentication.
(See IBM Integration Bus on Cloud in the IBM Cloud Shop.)

[3] The IBM Integration Bus for Developers toolkit was used to deploy and test the CustomerDatabaseV1 REST API on a local integration server (result of downloading the IIB on Cloud sample BAR file and then deploying into the IBM Integration Toolkit to run on an integration server there, or from completing the tutorial to create the REST API). The IIB web UI was used for initial testing of the REST API. A REST client was used for more realistic testing of API operations.


3:41min

This article also outlines the steps that were used to create the scenario to the point that the REST API was successfully tested through IBM API Management on Cloud in a secured environment.


Pushing a REST API to IBM API Management on Cloud

The REST API, CustomerDatabaseV1, is deployed on a local integration server in the IBM Integration Toolkit.
iibtoolkit_pustoapim0

To push this REST API to IBM API Management on Cloud, you only need complete the following few steps in the IBM Integration Toolkit:

  1. Right-click the deployed REST API and then click Push to API Connect.
    Note: The wizard refers to API Connect as the common term, with version 4 (for API Management) indicated on the final Success page.
  2. Enter the connection details for your IBM API Management account in the Host and Port fields.
  3. Enter your credentials for accessing IBM API Management in the User ID and Password fields, and then click Next. A connection is made to the IBM API Management server with which your credentials are associated, and the returned Organization is shown.
  4. To register the REST API on IBM API Management, click Finish.

The REST API can now be tested and used through IBM API Management on Cloud, with a little configuration of the API operations for the on Cloud environment.

Related information

The general procedure is described in the IIB product documentation: Pushing a REST API to IBM API Management or IBM API Connect.


Testing the REST API through IBM API Management on Cloud

To check that the REST API is defined and implemented correctly, you add its operations to a Plan in IBM API Management, and can then use the integrated test tool in the API Manager to try the operations. This does need a little configuration of the API operations for the on Cloud environment, to locate and authorize access to IIB on Cloud where the operations are to run.

Procedure: Add API operations to a Plan
  1. Sign in to API Management on Cloud: https://apim.ibmcloud.com/apimanager/
  2. Add the REST API operations to an IBM API Management plan.

    The plan enables a collection of operations from one or more APIs to be made available to consumers. For the current purpose we are using the Sandbox plan, which was created when testing a proxy REST API for the tutorial Create and Test a Proxy REST API used to test API Management.

  3. In the API Manager user interface, click Plans API Manager Plans icon
  4. Click the Sandbox link (the Plan name)
  5. Click +Operation

    API Manager; add operations to plan

  6. Ensure that Customer Database is the selected API in the left hand column, and then select the checkbox for all operations.

    API Manager selected operations to add to a plan

  7. Click Add. The operations are added to the Sandbox plan.
  8. Click Save
Procedure: Configure and invoke the GET (all customers) operation in the API Manager

Check that the REST API is defined and implemented correctly by using the integrated test tool in the API Manager to try the GET (all customers) API operation.

Perform the following steps on the APIs page. (To display the APIs page, click the APIs icon.)

  1. Edit the Customer Database API
    1. Expand the Customer Database row
    2. Click the Customer Database link (Title field)

    API Manager: Select Customer Database API

  2. Update the GET (all customers) operation to define the URI and basic authentication parameters needed to access IIB on Cloud.
    In this scenario, access to IBM Integration Bus on Cloud is controlled by basic authentication, which requires API requests to provide a valid user name and password to access operations. On the Implementation details of the operation in API Management you specify the user name and password, and the URL for the operation on IIB. This enables API consumers to request the operation from API Management without needing to specify the basic authentication details for IBM Integration Bus, and prevents consumers from making requests directly to IBM Integration Bus.

    In this example, to define the extra parameters, an HTTP GET operation is added between the request and response for the operation. For some operations, you also need to define the body passed between the request and response or define a mapping between data passed from request to response.

    1. On the APIs page for Customer Database, scroll down to the list of operations
    2. Select the GET operation (for “Get all customers from the database”), and then click the Edit icon API MAnager: API Edit icon
    3. Select the Implementation tab
    4. Select the Assemble tab
    5. Click the (+) icon
    6. Select the HTTP GET operation
    7. In the CONNECT step, complete the required property fields for the connector that is going to be used for the request activity.

      If you have already defined a connection for another operation with the same connection details, select that connection in the EXISTING CONNECTIONS field. Otherwise, specify the details for a new connection in the other fields. A description of the field values is given after the next image.

      apim_cloud_testop_addassemble3_testconnection

      Property name Description
      NAME Example: getcustomerdb
      Provide a name for your connection. This name is used in API Management for you to select any existing connections for operations with the same connection details.
      URL Example: https://ntge6jkt.ibmintegrationbus.ibmcloud.com/customerdb/v1/customers
      Provide the full URL for the operation from the integration in IIB on Cloud. The choice of “…/customers” or “…/customers/{customerId}” depends on the operation Path shown in API Management; for example, for GET all customers the Path is shown as “/customers”, which in IIB on Cloud gives the full path like the example https://ntge6jkt.ibmintegrationbus.ibmcloud.com/customerdb/v1/customers shown in the following image:
      IIB on CLoud: Service URLs showing a full path value
      USERID Example: iib
      Provide the user ID from the Basic Authentication section in IIB on Cloud; for example:
      IIB on CLoud: Basic authentication parameter values
      PASSWORD Provide the password from the Basic Authentication section in IIB on Cloud. To see the Password value, click the “eye” icon IIB on CLoud: Icon to show or hide password value next to the value.
    8. Click the button CONNECT. The status message indicates whether the connection test is successful.
      Important: You must click CONNECT to ensure that data entered in the fields is saved.
    9. In the DEFINE step, define the structure of the response body, in the following form:
      [
         {
            "id": 1,
            "firstname": "Denis",
            "lastname": "Darner",
            "address": "1 The Street, The Town"
         }
      ]
      

      Tip: You can discover this form by using a REST API client to submit the request to IIB (on Cloud or in the Integration Toolkit). You only need to define the structure of one customer.

    10. After entering/pasting this structure into request body, press the Tab key to have API Management format and check the body.
    11. Click Save at the top of the API page to save the changes
  3. Invoke the GET(all customers) operation to test its use through API Management.
    This passes the operation request from API Management on Cloud to IIB on Cloud and displays the response.

    1. Select the Test tab

      If you have only one environment and plan, the Environment and Plan fields are correctly populated. If you are working in an organization where this isn’t the case select the environment and plan that you want to use.

    2. Click Invoke

      The test result is displayed in the Response section; for the GET (all customers) operation, the response lists the details of all customers in the database.

      API Manager: Invoke GET all result

(Optional) You can test other operations as you want. The steps are generally the same as for the GET (all customers) operation

(Optional) Configure and invoke other API operations
(Optional) You can test other operations as you want. The steps are generally the same as for the GET (all customers) operation, but with some different requirements, including:

  • For operations on a specific customer (PUT and GET) with the path /customers/{customerId} you need to define another connection with the full URL for https://.../customers/{customerId}
  • For operations to create or change a customer record (PUT or POST), you add an equivalent HTTP PUT/POST operation and need to add the customer structure to the Request Body field

For example, to test the GET operation to get a specified customer from the database:

  1. Choose the GET operation for “Get a specified customer from the database”, and then click the Edit icon.

    Complete the steps as before for the GET (all customers) operation, except for the following:

    • In the CONNECT step, define a new connection as before, but with the full URI with the customerId parameter (from IIB on Cloud); for example:
      https://ntge6jkt.ibmintegrationbus.ibmcloud.com/customerdb/v1/customers/{customerId}
    • In the CONFIGURE step, select the Map Values tab, and then create a mapping from the input value customerId to the Input Variable customerId (drag the connection from one node to the other)
    • Click Save at the top of the API page to save the changes.

    • Invoke the operation to test its use on IIB on Cloud. This submits the operation request to IIB on Cloud and displays the response.
      1. Select the Test tab
      2. On the Parameters tab, enter the value of the customerId that you want to request
      3. Click Invoke
      4. The test result is displayed in the Response section; for the GET (customer) operation, the response lists the details of the requested customer.
        API Manager: GET customer success

For example, to test the POST operation to add a new customer to the database:

  1. Choose the POST operation for “Add a customer to the database”, and then click the Edit icon.
  2. Complete the steps as before for the GET (all customers) operation, except for the following:

    • On the Assemble tab, click the (+) icon and then select the HTTP POST operation
    • In the CONNECT step, select the existing connection that you used for GET (all customers) operation, for which the URL ends with /customers.
    • In the DEFINE step, define the structures for the request body and the response body, in the following forms.
      Note: To add a new customer, the operation takes a customer definition (without Id) and returns a string that contains the generated customerId.

      Tip: You can discover this form by using a REST API client to submit the request to IIB on Cloud.

      Request body Response body
      [
         {
            "firstname": "Denis",
            "lastname": "Darner",
            "address": "1 The Street, The Town"
         }
      ]
      
      {
         "message": "A new customer with ID '9' was successfully added to the database."
      }
      
    • After entering/pasting this structure into a body, press the Tab key to have API Management format and check the body.
    • In the CONFIGURE step, select the Map Values tab, and then create a mapping from the input values firstname, lastname, and address to the Input Variable parameters with the same names (drag the connection from one node to the other)
      API Manager: POST operation map parameters

    Click Save at the top of the API page to save the changes.

  3. Invoke the operation to test its use on IIB on Cloud. This submits the operation request to IIB on Cloud and displays the response.
    1. Select the Test tab
    2. On the Request body tab, specify the customer details for the input object in the following format:
      {
      "firstname" : "John",
      "lastname" : "Doe",
      "address" : "123 Main Street"
      } 
      

      After entering/pasting this structure into the body field, press the Tab key to have API Management format and check the body.

    3. Click Invoke

    API Manager: Invoke POST success

(Optional) Test that a REST client cannot call the API directly through IIB on Cloud
(Optional) Test that the API can be called from a REST client through API Management, but cannot be used directly through IIB on Cloud, without providing authorization on the request (Authorization=NoAuth)

A REST client was used for more realistic testing of API operations. If you do not have a dedicated REST client, most browsers, for example Google Chrome or Mozilla Firefox, have REST client extensions or add-ons that you can install in the browser.

For example, use a REST client to do the following:

  1. Call the API operation GET (all customers) with Authorization: NoAuth, using API Management hostname; for example: https://api.apim.ibmcloud.com.../customerdb/v1/customers

    The response provides the list of all customer details. (Click the image for a full-size view)
    REST client: GET (all customers) through APIM success with noauth

  2. Call the same API operation GET (all customers) with Authorization: NoAuth, using the IIB on Cloud hostname; for example: https://ntge6jkt.ibmintegrationbus.ibmcloud.com/customerdb/v1/customers

    The response indicates the authorization failure with “You need a valid user and password to access this content.” (Click the image for a full-size view)
    REST client: GET (all customers) direct to IIB fail with noauth


Extra information: Creating the scenario environment

The Push to API Management action only works if the scenario environment is already in place, with IBM Integration Bus able to connect to IBM API Management. To create the example environment from scratch, I completed the following activities. If you already have IBM accounts for the Cloud, or have your own local environment, you should be able to adapt these activities for your situation.

Creating the example scenario
  1. Use your IBM ID to register for A free trial account for API Management on Cloud. Alternatively, you can use a trial with API Management on Bluemix.
  2. Complete the tutorial Create and Test a Proxy REST API used to test API Management … and create a sandbox Plan.
  3. Use your IBM ID to register for A free trial account for IBM Integration Bus on Cloud (IIB on Cloud)
  4. Complete the activities for the IBM Integration Bus on Cloud sample, as described in Exploring IBM Integration Bus on Cloud by using a sample. This includes downloading the BAR file for the CustomerDatabaseV1 REST API, which you can later use for local testing in IBM Integration Bus for Developers and to push the REST API to IBM API Management.
  5. Use the Integration Toolkit (of an on-premises IBM Integration Bus) to create a local integration server for the REST API.

    Note: If you haven’t got a local IBM Integration Bus, you can download and install IBM Integration Bus for Developers without charge, as described in Getting started with IBM Integration Bus for Developers.

    1. In IBM Integration Bus for Developers, create an integration node to isolate local testing of the REST API. To later use a REST client to test the REST API on the local integration server requires some special configuration for the integration server.
    2. To ensure this scenario does not interfere with other scenarios, create and use a separate integration node, RESTNODE. This is the same as for the self-study IBM Betaworks Lab, [iib10] Lab 2: Developing a REST API service; section “1.2 Create and configure a new node for REST”.

      To create and configure the integration node, download the Lab file from the page [iib10] Lab 2: Developing a REST API service, and then complete the following steps:

      1. Extract the Lab file to C:\ to create the directory C:\student10.
      2. Open an IBM Integration Console window (Start > All Programs > IBM Integration Bus… > IBM Integration Console…)
      3. In the Integration Console window, change directory to C:\student10\REST_service\install, and then run the script: Create_RESTNODE

        Accept the default values for the IIB node name (RESTNODE) and other options.

      Note: Detailed instructions are provided in section “1.2 Create and configure a new node for REST” of the Lab guide available from the page [iib10] Lab 2: Developing a REST API service.

  6. Use the Integration Toolkit to deploy the CustomerDatabaseV1 REST API on the local integration server.
    Deploy the CustomerDatabaseV1 REST API to a local integration server, using the BAR file downloaded from IBM Integration Bus on Cloud in the earlier step to complete the activities for the IBM Integration Bus on Cloud sample. For this to work, the integration node must be running.

    1. In the Integration nodes pane, expand the node RESTNODE. If the node is not running, right-click RESTNODE and then select Start.
    2. Right-click the integration server (default), and then click Deploy, to display the Resources window
    3. In the Resources window, select the checkbox “BAR from file system”, and then browse and select the BAR file downloaded from IBM Integration Bus on Cloud.
    4. Click OK, to deploy the sample CustomerDatabaseV1 REST API to the local integration server.

    When the deploy action has finished, you can expand the integration server to show the CustomerDatabaseV1 deployed.
    IIB Toolkit: REST API deploed on integration server

This has created the scenario environment such that you can push the REST API to IBM API Management as described earlier in Pushing a REST API to IBM Management on Cloud

From this point, you can also test the REST API locally, by using the Integration Bus web UI or a REST client. You can also learn how develop the REST API by completing the tutorial “Manage a set of records with IBM Integration Bus REST API services” described in the Integration Toolkit.

For example, to view information about the deployed REST API and its operations, you can use the Integration Bus web UI:

  1. Open the IIB web UI by right-clicking RESTNODE and selecting Start Web User Interface. You will be switched to the Integration Bus web UI in your default browser.
  2. In the Integration Bus web UI, fully expand RESTNODE, down to the CustomerDatabaseV1: RESTNODE > Servers > default > REST APIs > CustomerDatabaseV1
  3. Under CustomerDatabaseV1, click “API”, which will show you the available operations in IIB and that they have been implemented. It will also show you the URLs for local and remote invocations, and the REST API definitions (the .json file).
    (Click the image for a full-size view)
    IIB web UI showing the REST API
  4. On “Remote URL for REST API definitions”, right-click and select “Copy Link Location” (the URL for the .json file); for example: http://9.174.22.125:7800/customerdb/v1/swagger.json
  5. In a browser tab/window, paste the copied URL, and then press Enter. You should see the contents of the Swagger file for the REST API.

You can also use a REST client to test operations of the REST API; for example: (Click the image for a full-size view)
REST client: Test API in local IIB

Join The Discussion

Your email address will not be published. Required fields are marked *