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 Connect (on IBM Bluemix). This uses the Swagger file for the REST API to register the API with IBM API Connect, without you needing to do anything else. You can then use IBM API Connect 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.
  1. Overview
  2. Pushing a REST API to IBM API Connect (on Bluemix)
  3. Testing the REST API through IBM API Connect
  4. (Optional) Test that a REST client cannot call the API directly through IIB on Cloud (Authorization=NoAuth)
  5. (Optional) Test that the API cannot be invoked through API Connect, without providing authorization on the request (Authorization=NoAuth)

Overview

This article shows you how easily you can push a REST API from the Integration Toolkit of IIB on premises to IBM API Connect (on IBM Bluemix), and then use API Connect to manage access to the REST API deployed into IIB 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 Connect (on IBM Bluemix)

Scenario diagram notes:

[1] A free trial account for IBM API Connect (on Bluemix) was created, and then the Getting started with API Connect steps used to test API Connect … and create a Sandbox catalog for products. (If you haven’t done so already, you first need to setup an IBM Bluemix account.)

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

[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 examination of the REST API. A REST client was used for more realistic testing of API operations.

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 Connect in a secured environment.


Pushing a REST API to IBM API Connect (on Bluemix)

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

The IIB web UI was used to push the API to API Connect because the push function has options to create a Product and stage that product to a Catalog in API Connect in the same push action. Alternatively, you can just push the REST API to API Connect, by using either the IIB web UI or push function in the IIB Toolkit, and then later use API Connect to work with the REST API, product, and catalog.

To make an API available to a customer, it must be included in a Plan. Both the API and Plan are contained within a Product. Plans are used to differentiate between different offerings. Additionally, you can enforce rate limits through Plans or through operations within a Plan’s APIs that override the Plan’s rate limit. Products are then published in a Catalog. Through Products, you can manage the availability and visibility of APIs and Plans. For more information about Products and Plans in API Connect on Bluemix, see Managing APIs at https://new-console.eu-gb.bluemix.net/docs/services/apiconnect/apic_006.html#apic_006.

The IIB web UI, showing the integration server option to push REST APIs to IBM API Connect

iibtoolkit_webui_pushtoapi1a

Procedure

To use the IIB web UI to push this REST API to IBM API Connect, you only need complete the following few steps:

  1. Click the drop-down menu for the integration server (default), and then click Push REST APIs to IBM API Connect.

    Result: The Push REST APIs to IBM API Connect wizard appears:
    iibtoolkit_webui_pushtoapi2

  2. Enter the connection details for your IBM API Connect account in the Host and Port fields.
    • Host: The host name is shown in the address of your API Connect on Bluemix web UI, and depends on the Bluemix region your account belongs to; for example: eu.apiconnect.ibmcloud.com (United Kingdom), us.apiconnect.ibmcloud.com (US South), au.apiconnect.ibmcloud.com (Sydney)
    • Port: leave this as 443.
  3. Enter your IBM ID credentials for accessing IBM API Connect in the UserID and Password fields
  4. Click Connect to IBM API Connect.

    Result: A connection is made to the IBM API Connect server with which your credentials are associated. You should see the following message: “Successfully connected to API Connect”

  5. Click Next

    Result: On the Specify the product… page, you are prompted to add a new product that will contain the REST API.

    iibtoolkit_webui_pushtoapi4_stage2catalog

  6. Specify the product title: Customer. (The name and version are generated for you.)
  7. Select the Sandbox catalog into which to stage the product for use. (Option: If you do not stage the product at this time, you can do so later in API Connect.)
  8. Click Next
  9. On the Select APIs page, select the CustomerDatabaseV1 API
  10. To register the REST API on IBM API Connect, click Push to IBM API Connect.

    When the REST API has been pushed to API Connect successfully, success messages are shown:

    iibtoolkit_webui_pushtoapi8success

  11. Click Close

If you log in to IBM API Connect, you should see the product created and the draft API that has been pushed from IIB:

IBM API Connect, Products showing the new product created by the REST API push from IBM Integration Bus

apiconnect_product

IBM API Connect, Draft APIs showing the REST API pushed from IBM Integration Bus

apic_bluemix_0_drafts_apis

You can now use API Connect to explore and test the REST API.

Related information

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


Exploring the REST API in IBM API Connect

  1. You can use the API Manager in API Connect to explore the REST API.

    If you are not logged in to IBM API Connect on Bluemix, log in now; for example:

    1. In your My Applications and Services page, https://myibm.ibm.com/products-services/, launch IBM Bluemix
    2. In Bluemix, select your API Connect instance
    3. If you are not automatically logged in, log in with your IBM ID and password

    Result: You are now logged on to IBM API Connect as an API manager.

  2. Display the Drafts > APIs view. If this is not shown when you log in to API Connect, Click the menu symbol apiconnect_bluemix_2-menu_symbl, then click Drafts, and then click APIs.

    Hint: You may get an introductory pop-up for each of the first few pages. Whenever you get the pop-up, click Got it! when you have finished reading it.

    Result: The Drafts > APIs view lists the Customer Database API that you pushed from IBM Integration Bus:
    apic_bluemix_0_drafts_apis

  3. To show the details of the API in the API Editor, click Customer Database
  4. In the API Editor, explore the design of the API by navigating the left panel or scrolling the pane at the right. For example, in the Schemes section under the Design tab note that only the https check box is selected, which ensures request for the published API will be secured using https.

    Access to the REST API can be restricted by use of a Client ID and Client Secret which can be defined in the Security Definitions section and referenced in the Security section below it. The security definitions are not used at this point.
    apic_bluemix_1_drafts_apis_details

When you are ready to start testing the API, continue with the next section.


Testing the REST API through IBM API Connect

This section assumes that you have added the REST API to a Plan and Product, and that Product is staged in the Sandbox catalog, as described in the previous section. You can test the REST API as a draft API, but for the API to become available to application developers, the Product must be staged to a catalog and then published to Developer organizations.

The REST API as pushed from the IIB web UI references the API deployed on the local integration server (in the IBM Integration toolkit). To test the API deployed to IIB on Cloud needs a little configuration, to locate and authorize access to IIB on Cloud where the API operations are to run.

Stages:

  1. Configuring the API Connect proxy to access IIB on Cloud
  2. Testing REST API operations through API Connect

Configuring the API Connect proxy to access IIB on Cloud

  1. In the API Editor view of the API, click the Assemble tab

    Result: The API’s assembly flow is shown, with a proxy node.
    apiconnect_bluemix_1_drafts_apis_assemble0_click

    IBM API Connect will proxy the requests for the REST API into IBM Integration Bus. The URL value of the proxy node is the proxy address in API Connect which will invoke the real REST API in IIB.

  2. To view and edit the proxy details, click the proxy node.

    When the REST API was pushed into API Connect, the definition contained the host and port for the local integration server in IIB (on premises); you should see these in the URL value.
    apiconnect_bluemix_1_drafts_apis_assemble1proxyurl_local

    We could use API Connect to test use of the REST API running in IIB on premises, by installing and configuring the IBM Bluemix Secure Gateway Client to enable secure access to the local integration server. (This is the subject of a separate tutorial, in the blog post Pushing REST APIs to IBM API Connect provisioned on Bluemix and accessing them through a Secure Gateway service.)

    For API Connect to proxy requests for the REST API running in IIB on Cloud, we change the proxy URL to the IIB on Cloud host.

    Also, access to IIB on Cloud is secured by basic authentication, which requires API requests to provide a valid user name and password to access operations, so for testing we specify the ID and password values on the proxy. (This enables API consumers to request the operation from API Connect without needing to specify the basic authentication details for IIB on Cloud, and prevents consumers from making requests directly to IIB on Cloud without the user name and password.)

    To determine the host URL, ID and password, log in to IIB on Cloud, and then complete the following steps:

    1. Click CustomerDatabaseV1
    2. Click Public Endpoints
      • Under Basic Authentication, note the User and Password values. (To see the hidden password, click the eye icon.)
      • Under Service URLs, note the Host value.

      For example:
      iiboc_customerdatabasev1_publicendpoints

      Hint: Keep the IIB on Cloud web page open, because you will need to copy more details and to use it to start the REST API.

  3. Copy the Host value and then paste it into the proxy URL field, to replace the http://host:7800 part before ${request.path}; for example: https://flijkpnh.ibmintegrationbus.ibmcloud.com${request.path}

    If you change a value in the proxy details, the Save (disk) icon changes from grey to blue.

  4. Copy the User and Password values, and then paste them into the Username and Password fields; for example:
    apiconnect_bluemix_customerdb_product_pwd

    Note: In the above image, I used the Password value xxxxxxx just for this image; you should copy and paste the real value from your IIB on Cloud.

  5. To save your changes, click the blue Save (disk) icon. You will see a “Success API saved” message:
    apiconnect_bluemix_customerdb_success_api_saved
  6. To close the proxy details pane, click the X (Close) icon at the top of that pane.

Testing REST API operations through API Connect

You can check that the REST API is defined correctly in API Connect, by using the Test tool in API Connect to invoke API operations like getAllCustomers.

Before invoking API operations, ensure that the REST API (integration) is running in IIB on Cloud. Check your IIB on Cloud web page, and if needed start the API by clicking Start and then waiting for the status to change to Running.

In API Connect, complete the following steps on the APIs > Assemble pane.

  1. Click the Test (“play”) icon
    apiconnect_bluemix_1_drafts_apis_test_play

    Result: The Test pane is displayed:
    apiconnect_bluemix_customerdb_product_test_pane

    Note, under Setup, the information “Sandbox, Customer 1.0.0, using automatic subscription”. The REST API has been added to the product Customer 1.0.0, published in the Sandbox catalog. That catalog is a development catalog configured with automatic subscription, so you do not need to provide an application to run the API because a test application is used automatically. For information about catalogs and automatic subscription, see Working with catalogs.
  2. Because we have changed the proxy values in the API, we have to republish the Product that contains the API before we can test the API.

    Click Republish product.

  3. Use the Operation field to select an operation to invoke; for example, getAllCustomers. (If you choose some other operations, you may need to specify parameter values.)
  4. Scroll down the Test pane to show, and then click, Invoke. This passes the operation request from API Connect to IIB on Cloud and displays the response.

    For a successful operation, the Response section shows a Status code of 200 OK, and the contents of the Body returned from IIB on Cloud. For example, for getAllCustomers:
    apiconnect_bluemix_customerdatabasev1_proxy2iib_getsuccess_200

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

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

Choose the operation addCustomer, and then in the body* field enter the new customer definition (without Id, which will be assigned), and then click Invoke. In the Response body you should see a success message; for example:

Request body

{
  "firstname": "Sherlock",
  "lastname": "Holmes",
  "address": "221B Baker Street, London"
}

Response body

{
   "message": "A new customer with ID '9' was 
    successfully added to the database."
}

Congratulations! You have successfully implemented a scenario for a REST API in IIB on Cloud managed and accessed through API Connect on Bluemix:
Diagram of scenario for REST API in Integration Toolkit, deployed to IIB on Cloud, and its Swagger file pushed to API Connect (on IBM Bluemix)


(Optional) Test that a REST client cannot call the API directly through IIB on Cloud (Authorization=NoAuth)

(Optional) Test that the API can be called from a REST client through API Connect, 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 complete the following steps:

  1. Call the API operation getCustomer with Authorization: NoAuth, using API Connect URL; for example: https://api.eu.apiconnect.ibmcloud.com/.../sandbox/customerdb/v1/customers

    The response provides the list of all customer details, because the basic authorization parameters needed by IIB on Cloud are defined in the API Connect proxy.
    postman_apic_customersget_noauth_apicproxyauth

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

    The response indicates the authorization failure with “You need a valid user and password to access this content.”
    postman_iiboc_customersget_noauth_iib


(Optional) Test that the API cannot be invoked through API Connect, without providing authorization on the request (Authorization=NoAuth)

In this scenario, access to IIB on Cloud is controlled by basic authentication, which requires API requests to IIB on Cloud to provide a valid username and password to access API operations. For testing in API Connect, you configured the API proxy details with the username and password, and the URL for the API in IIB on Cloud. This means that API consumers with access to the API can request the operation through API Connect without needing to specify the basic authentication details for IIB on Cloud.

You might want to further secure access to the API operations, by removing the username and password values from the API proxy details to force API consumers to specify the values when they invoke an API operation through API Connect.

  1. In the API Editor, edit the proxy details for the draft API Customer Database, to delete the values for user name and password.
    apiconnect_bluemix_1_drafts_apis_assemble_noauth_uidpwd
  2. Save your changes, and then click the play icon to test the API.
  3. Click the button to republish the product
  4. Choose an operation to invoke; for example, getCustomer
  5. Scroll down the Test pane and then click Invoke.

    Note that the response is 401 Unauthorized: You need a valid user and password to access this content.

  6. Use a REST client to invoke the API operation through API Connect (with Authentication: noAuth)
    Note that the response is 401 Unauthorized, because the username and password are not set on the proxy (when they were for earlier successful tests).
  7. Use a REST client to invoke the API operation through API Connect (with basic authentication set with the username and password for IIB on Cloud)

    Note that the response is successful, because the username and password are provided by the Rest client as the API consumer.
    postman_iiboc_customersget_iib_basicauth_crop

If you invoke the API operation against IIB on Cloud through a web browser, you are prompted for the username and password before the API operation can be invoked.


Extra information: Creating the scenario environment

The Push to API Connect action only works if the scenario environment is already in place, with IBM Integration Bus able to connect to IBM API Connect. 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 setup an IBM BlueMix account.
  2. Use your IBM ID to create a free trial API Connect service (on Bluemix)
  3. Complete the Getting started with API Connect tutorial to test API Connect … and create a Sandbox catalog for Products.

    To make an API available to a customer, it must be included in a Plan. Both the API and Plan are contained within a Product. Products are then published in a catalog.

    • Plans are used to differentiate between different offerings. Also, you can enforce rate limits through Plans or through operations within a Plan’s APIs that override the Plan’s rate limit.
    • Products are used to manage the availability and visibility of APIs and Plans.

    For more information about Products and Plans in API Connect on Bluemix, see Managing APIs.

  4. Use your IBM ID to register for a free trial account for IBM Integration Bus on Cloud (IIB on Cloud)
  5. 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 Connect.
  6. 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.

  7. 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 Connect as described earlier in Pushing a REST API to IBM Connect

From this point, you can also test the REST API locally; for example, using the IIB web UI to examine the REST API and then using a REST client to invoke API operations. 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.

IIB product documentation about viewing the deployed REST API in the web UI: Managing a deployed 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 *