Learn how to use the embedded API management capabilities in IBM App Connect on IBM Cloud to secure, test, and socialize APIs that are exposed when you create flows for APIs.

API management is integrated into App Connect services, Cloud Foundry applications, and Cloud Functions actions, and enables users in an IBM Cloud organization to:

  • Build or expose APIs, and test them.
  • Control and manage access to APIs by configuring security schemes.
  • Manage API usage by enforcing rate limits for API calls from consuming applications.
  • Increase adoption by sharing APIs, and by exporting API definitions.
  • Track API usage and monitor API call volumes through analytics and logging.
  • Transfer APIs to IBM API Connect for more advanced API management.

Note: This information applies only if you are using an IBM App Connect on IBM Cloud service.

Additional reference:
IBM Cloud
Getting started with IBM App Connect on IBM Cloud
API management overview

Steps for completing this tutorial:

First, find or create everything you need:

  1. Obtain access to an App Connect service on IBM Cloud:
    1. Complete one of the following steps:
    2. From the IBM Cloud dashboard, click your App Connect service.

      IBM Cloud dashboard

    3. Click Manage in the navigation pane and then click Launch App Connect to open the App Connect dashboard.

      Launch App Connect

  2. For use in this tutorial, we’ve provided a sample YAML file that contains the flow definitions for an API that creates, retrieves, and replaces or creates customer contacts in a Salesforce (CRM) system. To use this flow definition file:
    1. Download the Customer-API-management-API.zip file and extract the Customer APImanagement API.yaml file to a preferred location. (You’ll import this file into App Connect in a later step.)

      Tip: The supplied YAML file was created as follows:

      1. We used the instructions in the following tutorials to create flows for an API named Customer APImanagement API: Creating flows for an API (Part 1) and Creating flows for an API (Part 2). The Customer model properties were defined as CustomerID, FirstName, LastName, and Email.
        (If you’d like to learn how to create flows for an API, you can follow the steps in these tutorials to create the flows from scratch later.)
      2. We exported the API flow definitions to a YAML file.
        (App Connect’s export/import functions enable you to share event-driven and API flows with other App Connect users who want to configure identical or similar integrations. If you’d like to learn more about exporting and importing flows, see How do I export and import flows?)
    2. You’ll need a Salesforce account. (The flow definitions in the supplied YAML file use Salesforce as the target application.)

      If you want to create a free test account in Salesforce rather than use your business account, make sure that you sign up for a Developer account rather than a Trial account.

    3. If you haven’t already connected App Connect to Salesforce, you’ll need the user name and password for your Salesforce account. Based on the type of Salesforce environment, you might also need to provide a custom URL for your production org, sandbox, or subdomain. For more information about these connection details, see How to use IBM App Connect with Salesforce.
      • If you haven’t yet connected, follow these instructions to connect now…

        If you haven’t yet connected to Salesforce, go to the Applications tab on the App Connect Catalog page, expand the Salesforce entry, click Connect, and then enter the account information. (You can also connect to an application from within a flow.)

        Connect to Salesforce

Note: During this tutorial, you’ll learn how to transfer your API to IBM API Connect so it can be viewed and managed from there. If you do not already have an API Connect service, we’ll automatically provision an API Connect Lite (free) service for you when the API is transferred.

Next, create your flow by importing the flow definition YAML file:

Let’s now import the extracted Customer APImanagement API.yaml file from earlier into App Connect:

  1. Go to the App Connect dashboard, click New, and then click Import flow.
  2. Click within the Select file boxed area to open a file browser, and locate and select the .yaml file. You’ll see the file name in the boxed area.

    Select YAML file to import

  3. Click Import.

    The imported flow should open with the Define tab on display.

    Define tab for an API flow

  4. Examine the Customer model’s properties, which were added to define the API’s data objects. The FirstName, LastName, and Email properties will be used to supply details of a customer contact to be created or replaced in Salesforce. The CustomerID property represents the contact ID that Salesforce generates when a record is created, and which can be used to retrieve the record.
  5. Click the Operations tab to view the create, retrieve, and replace or create operations that were implemented for the Customer model.

    Operations for the Customer model

  6. Validate the settings for each of the three operations in turn as follows:
    1. Click Edit flow. Then click and examine the Request, Salesforce, and Response nodes to help you understand how the flow works. Ensure there are no validation errors (depicted with a warning icon Warning icon for flow validation) on any of the nodes.

      Tip: If you see a Not connected validation error on the Salesforce node, it might be because your Salesforce account name is different from the one used in the flow definition that you just imported, or because you are connected to multiple Salesforce accounts. To resolve this error on the Salesforce node, click the Not connected drop-down list and then select the required account. For example:

      Selecting an account

    2. Click Done.
  7. When you’ve validated all your operations, start the API by selecting Start API from the flow menu (⋮).

    Start API option

    The API is shown as running.

    API depicted as running

Finally, manage the API that’s exposed by the implemented flows:

The defined configuration of the implemented flows provides an API that can be managed by the API management capabilities in IBM Cloud. In this section, you’ll learn how to secure and test the API, view details about the API’s usage and responses, define sharing policies for the API, and transfer the API to IBM API Connect.

Step 1: Access the API management facilities

To access the API management facilities:

  1. Click the Manage tab.

    Manage tab for API flows

  2. Briefly examine the contents of this tab. At the top, you’ll see the API name and the URL (route) where the API is exposed on the API management gateway. Also notice that rate limiting and sharing are not initially enforced, but that authentication via an API key and CORS support are enabled by default.

    The remainder of the tab provides sections for analytics and logging, API transfer or export, security, rate limiting, and sharing.

Step 2: Configure a security scheme and rate limiting options for the API

Let’s start by configuring a security scheme and rate limiting options for the API:

  1. Scroll down to the Security and Rate Limiting section. From this section, you can indicate whether you want consuming applications to use authentication when making API calls, and whether to enable OAuth user authentication. You can also configure rate limiting and cross-origin resource sharing (CORS) support.

    Security and Rate Limiting

  2. Ensure that the Require applications to authenticate via API key slider is set to on (the default).
  3. In the Method field, ensure that the selection is API key only. (We’ll generate an API key later.)
  4. In the Location of API key and secret field, accept the default Header value. (We want the API key to be contained in the header when making API calls.)
  5. In the Parameter name of API key field, accept the default value. (This parameter name will be used to store the API key in the header.)

    Tip: The Parameter name of API secret field is enabled only if you selected a value of API key and secret in the Method field, and defines a parameter name that will be used to store the API secret in the header.

  6. Under Rate limiting, set the Limit API call rate on a per-key basis slider to the on position. Then set the maximum number of API calls to 1000 per minute. (This setting defines the number of calls permitted for each API key that you create.)

    Rate limiting, OAuth, and CORS options

  7. Leave the Require users to authenticate via OAuth social login slider in the off position. (For this tutorial, we don’t want to enforce OAuth access for the API by using social login credentials of providers like IBM Cloud App ID, Google, Facebook, and GitHub.)
  8. Leave the Enable CORS so that browser-based applications can call this API slider in the on position. (We want to enable the API to retrieve information from another domain when it’s called by the API.)
  9. To save your settings, click Save.

Step 3: Test the API flows

Next, let’s explore how to share the API with a user outside your organization, and also test the API flows by using the built-in facilities:

  1. Scroll down to the Sharing Outside of Cloud Foundry organization section at the bottom of the page. From this section, you will create an API key for a user outside your organization, and generate an API portal link. (You can generate a maximum of five API keys to help you track API usage by user. If you’re generating multiple API keys, you might find it helpful to give each API key a descriptive name that helps you identify the user that you intend to assign that key to.)

    Sharing Outside of Cloud Foundry organization section

  2. Click Create API key. Notice that a generated API key is automatically provided in the “Create API key” window.
  3. Enter Customer APImgmt key as the descriptive name for the key, and then click Create.

    API key for testing flow for API in API portal

    In the Sharing Outside of Cloud Foundry organization section, you’ll see an entry for the newly created API key together with an API portal link.

    Entry for the newly created API key together with an API portal link

    Tip:

    • You can share the API with a user outside your organization by sending them the API portal link so they can explore and test the API within an API Explorer window. You can right-click over the link and copy the link address to pass on.
    • When you copy and paste the API portal link, notice that the generated API key is shown as the value of the clientId query parameter; for example:
      https://service.us.apiconnect.ibmcloud.com/fusion/devportal/portal?artifactId=apc-VhqGvm&clientId=9876f5a4-a444-432d-87b7-5157f7f7a567
    • You can also use this link to test the API yourself, as described in the steps that follow.
  4. Click the API portal link to open the API in the API Explorer window (new tab). You’ll test your API from here.

    The left pane shows the configured operations and model. You can click any of these entries to view related details in the adjacent panes. The middle pane displays the security scheme, parameters, and response codes for the operations, as well as model properties, and the right pane provides test facilities for calling the endpoints. Next to the API name in the middle pane, notice also that there’s a Download icon Download icon, which you can use to download the OpenAPI document that describes this API.

    (Click the image to view its full size.)
    API Explorer window

  5. To test the create operation that was configured in the flows for the imported API, click Customer.create under Operations in the left pane to ensure the relevant fields are in focus.
  6. In the right pane, leave curl as the default tooling language to be used when making the request, and review the code sample of the request. In the curl sample, notice that the API key is included in the header using the x-ibm-client-id parameter. (You can optionally expand the Example request drop-down list to choose other languages and view code samples for calling the operation in those languages.)
  7. To invoke the POST operation for your API in the API Explorer, click Try it.

    (Click the image to view its full size.)
    Testing the Customer.create operation

  8. To generate sample data that can be used in your test request, click Generate next to the data field. The sample data is shown in the data field and will be used to create a Salesforce contact. (This sample shows a JSON representation of the data that anyone who calls the API should provide.)

    Generate sample data to test the Create  operation

  9. Delete the CustomerID entry from the sample data because an ID does not need to be provided when creating a contact in Salesforce. Instead, Salesforce will generate an ID for the newly created contact and return it in the response. (The CustomerID entry is generated by default in the sample because we defined it as one of the properties for the Customer model.)

    Your sample data should now look something like this:

    Revised sample data for the Create operation

  10. Click Call operation.
  11. Scroll down to see a summary of the request and the response. In the Response section, you should see the success code: 201 OK and the response body containing the CustomerID value assigned by Salesforce.

    Response content after the Call operations button

    Tip: If you go to your Salesforce UI, you’ll notice that a new contact has been created using the sample data that you generated. Notice that the contact ID shown in the URL for the record is identical to the CustomerID value shown in the Response in the API Explorer window.

    New contact record in Salesforce

  12. In the API Explorer window, test the retrieve operation as follows:
    1. Copy the CustomerID value returned by Salesforce for the create operation and paste it into a text editor. Based on our specific example above, this value is 0030Y00001Aczl1QAB, but it will be different for you.
    2. In the left pane, click Customer.findById under Operations. (We are going to retrieve a Salesforce contact’s details by specifying an ID.)
    3. In the right pane, click Try it to invoke the GET operation for your API.

      Testing the Customer.findById operation

    4. In the id field, paste the CustomerID value that you copied earlier.

      Specifying an ID for a contact to be retrieved

    5. Click Call operation.
    6. Scroll down to see a summary of the request and the response. In the Response section, you should see the success code: 200 OK and the response body containing the CustomerID value, as well as the values retrieved from Salesforce for Email, FirstName, and LastName.

      Response content after the Call operations button

  13. In the API Explorer window, test the replace or create operation as follows:
    1. Copy the JSON returned in the response body for the previous retrieve operation and paste it into a text editor. Based on our specific example above, this JSON is as follows (though it will be different for you):
      
      {
        "CustomerID": "0030Y00001Aczl1QAB",
        "Email": "ipfu@eszup.cc",
        "FirstName": "Willie",
        "LastName": "Garcia"
      }
      
    2. In the left pane, click Customer.prototype.updateAttributes under Operations. (We are going to update a Salesforce contact’s details by changing their email address.)
    3. In the right pane, click Try it to invoke the PUT operation for your API.

      Testing the Customer.prototype.updateAttributes operation

    4. In the data field, paste the JSON that you copied earlier. Then, copy the CustomerID value and paste it into the id field.
    5. In the data field, delete the CustomerID entry. Then, change the value of the Email property to newemail@example.com.

      Updating the email address for a contact

    6. Click Call operation.
    7. Scroll down to see a summary of the request and the response. In the Response section, you should see the success code: 200 OK and the response body containing the CustomerID value, as well as the updated Email address, and unchanged FirstName and LastName values.

      Response content after the Call operations button

      If you go to your Salesforce UI and refresh, you should notice that the email address for your sample contact has been updated.

  14. Go back to the Manage tab for the API and scroll to the top. Notice that the Rate Limit pane displays the limit that you set earlier, and that the Sharing pane now indicates that one API key is being shared with users outside your organization. Also notice that invocation and response statistics are now logged for the API in the Analytics and Logging pane. (Be aware though that statistics are retained for only one hour from the time of invocation.)

     Updated Rate Limit, Sharing, and Analytics and Logging panes

Step 4: Transfer the API to IBM API Connect for IBM Cloud

Now, let’s automatically transfer the API to IBM API Connect for IBM Cloud to take advantage of its advanced API management capabilities. IBM API Connect is an integrated API management offering, where all phases of the API lifecycle (for creating, running, managing, and securing APIs), are performed within the offering. Capabilities include automated creation of APIs, lifecycle management and governance for APIs, fine-grained access control over APIs, customizable, self service portals for publishing APIs for discovery and use, and advanced API usage analytics.

  1. Scroll down to the API Info section.
  2. To transfer the API to API Connect, expand the API definition drop-down list and click Open in API Connect.

    Open in API Connect option

    You’ll see the following message, which informs you that your API will be transferred to API Connect, and that an API Connect service with a free Lite plan will be automatically provisioned for you if you do not have one already.

    API Connect transfer message

  3. Click Continue.
    • If you don’t already have an existing API Connect service, you’ll see a message indicating that the service is being provisioned, and on completion, you’ll see a confirmation message.

      Confirmation message for provisioned API Connect service

    • If you already have an existing API Connect service, you’ll see a message indicating that the API is being transferred, and on completion, you’ll see the following confirmation message.

      Confirmation message for provisioned API Connect service

  4. Click the Launch API Connect in a new browser tab link.

    When API Connect opens in a new browser tab, click Got it to close the “Draft APIs” help overlay. You’ll see the API in the APIs tab of the Drafts page, which is used to design and configure APIs and Products in API Connect.

    API in the API Manager Drafts view

    You can click the API to edit its definition further, as described in Composing a REST API definition in the API Connect for IBM Cloud documentation. For more information about working with this API in API Connect, see also Managing your APIs in the API Connect documentation.

    Note: A new management endpoint is created for the API that was transferred to the API Connect environment. This new endpoint can be configured independently of the original one in your App Connect environment; so, configuration changes to one management endpoint will not be reflected in the other.

Step 5: Share the API with other members of your IBM Cloud organization

Finally, let’s share the API with other members of your IBM Cloud organization to make the API available for discovery.

  1. If you are still on the API Connect window for your transferred API, return to the Manage tab in App Connect. (If necessary, close the “Open Customer APImanagement API in API Connect” panel from which you launched API Connect.)
  2. Scroll down to the Sharing within Cloud Foundry organization section near the bottom of the page.
  3. Set the Include API in organization-level Shared APIs view slider to the on position.

    Sharing within Cloud Foundry organization section

  4. To create a key for the API, click Create API key. Notice that a generated API key is automatically provided. (You can create a maximum of five API keys.)
  5. Enter Customer SharedAPI key as the descriptive name for the key, and accept the default values for the API secret. You can click the Show check box to view the API secret. (Although an API secret is generated by default, it’s required for authentication only if Method was set to API key and secret in the Security and Rate Limiting section. For more information, see the Using an API key and secret with APIs that are shared within your org subsection under Additional tips for managing APIs.)

    API key for sharing an API in your organization

  6. Click Create. In the Sharing within Cloud Foundry organization section, you’ll see an entry for the newly created API key.

    Entry for the newly created API key

  7. From the Sharing within Cloud Foundry organization section, you can copy the API key (by clicking the copy icon Copy icon) and then send it to a user who wants to invoke your API as a shared API.

    Note: Users in your IBM Cloud organization will be able to see the API that you just shared from the IBM Cloud APIs console, and can subscribe to it. Shared APIs can be accessed by clicking the IBM Cloud menu IBM Cloud menu icon and then selecting APIs > Shared APIs.

    IBM Cloud menu

  8. The API that you just shared will also be added to the App Connect catalog of applications and APIs, enabling you to select this API for use within your flows. To view the shared API within App Connect, return to the App Connect dashboard, go to the Catalog page and then click the APIs tab. For more information, see How to use IBM App Connect with shared APIs in IBM Cloud.

    Shared API on the APIs tab on the Catalog page

Additional tips for managing APIs:

This section discusses alternative options that you can configure from the Manage tab of an API flow in App Connect.

Using an API key and secret with APIs that are shared outside your org

If Require applications to authenticate via API key is on (in the Security and Rate Limiting section) and you set the Method field to API key and secret, an API key is generated without any prompt for a secret when you click Create API key in the Sharing Outside of Cloud Foundry organization section.

Method field with the API key and secret setting

However, when you click the link under the API Portal Link column to open the API in the API Explorer window, you or the person you sent the link to will need to set the secret from that window by clicking Set API Secret.

Set API secret

You’ll see the following panel and can either accept the automatically generated API secret or specify a value of your own. Click the Show check box if you want to view the the API secret in plain text. Before you save, click Copy to copy the API secret and then store it somewhere – you’ll need to specify it together with the API key when calling the operation.

Setting the API secret

Tip: After you save the API secret, you’ll notice that the Set API Secret button is replaced with an Enter API Secret button. If required, you can use this button to view your API key and secret, and can use it to reset the secret.

The API Explorer window also provides example requests that can be used to call each operation. When you select an operation in the left pane, the Security section in the middle pane displays where the API key and secret will be located when calling the operation, and the right pane provides a set of example requests that you can use to call the operation. The following example shows a sample curl request that’s provided for a create operation. In this example, the REPLACE_THIS_KEY text can be overwritten with the actual API key and secret:


curl --request POST \
 --url https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/f35c6aa4dabcdecf6877799e16d6c6e8e56c79520d45eb9aa7bf8123456789ce8a/QBSEv5/Prod \
 --header 'accept: application/json' \
 --header 'content-type: application/json' \
 --header 'x-ibm-client-id: REPLACE_THIS_KEY' \
 --header 'x-ibm-client-secret: REPLACE_THIS_KEY' \
 --data '{"ProdID":"475696480649216","ProdName":"Jeanette Meyer","ProdDesc":"Bilka pahpoma gukef sa baas kuj kecak ducecre zuj icreh da dire puvi mir gubfaoja.","Email":"pa@neiri.net"}'

Using an API key and secret with APIs that are shared within your org

If Require applications to authenticate via API key is on (in the Security and Rate Limiting section) and you set the Method field to API key and secret, an API secret is automatically generated together with an API key when you click Create API key in the Sharing within Cloud Foundry organization section. (This assumes that Include API in organization-level Shared APIs view is also set to on in the Sharing within Cloud Foundry organization section.)

Method field with the API key and secret setting

Create API key and secret

Click the Show check box to view the API secret and make a note of the value. The API secret can be viewed only when it’s first set, and cannot be retrieved or reset afterwards.

After you click Create, you’ll see an entry for the newly created API key in the Sharing within Cloud Foundry organization section. You can copy the API key (by clicking the copy icon Copy icon) and then send it together with the API secret to a user who wants to invoke your API as a shared API.

Entry for the newly created API key

Users in your IBM Cloud organization will be able to view the shared API from the IBM Cloud APIs console, and can subscribe to it. Shared APIs can be accessed by clicking the IBM Cloud menu IBM Cloud menu icon and then selecting APIs > Shared APIs.

In the Summary view of an API, users in your org can see that both an API key and a secret are required to call the API, and can optionally use the Create API key button (in the Sharing within Cloud Foundry organization section) to generate an API key and a secret if fewer than five (the maximum) have been generated.

(Click the image to view its full size.)
Summary  view for generating API key and secret

In the API Explorer view of an API, users in your org can select an operation (in the left pane) to see where the API key and secret will be located when calling the operation (middle pane), and can use the example requests provided (in the right pane) to call the operation.

(Click the image to view its full size.)
API Explorer view with API key and secret

In the example curl request shown in the preceding image, the REPLACE_THIS_KEY text can be overwritten with the actual API key and secret when calling the create operation:


curl --request POST \
 --url https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/f35c6aa4dabcdecf6877799e16d6c6e8e56c79520d45eb9aa7bf8123456789ce8a/QBSEv5/Prod \
 --header 'accept: application/json' \
 --header 'content-type: application/json' \
 --header 'x-ibm-client-id: REPLACE_THIS_KEY' \
 --header 'x-ibm-client-secret: REPLACE_THIS_KEY' \
 --data '{"ProdID":"475696480649216","ProdName":"Jeanette Meyer","ProdDesc":"Bilka pahpoma gukef sa baas kuj kecak ducecre zuj icreh da dire puvi mir gubfaoja.","Email":"pa@neiri.net"}'

Note: Although shared APIs that require both an API key and a secret for invocation are displayed on the APIs tab of the App Connect Catalog page, you cannot connect to and use them in your flows because this security scheme isn’t supported in App Connect.

Switching off authentication for the API

From the Security and Rate Limiting section, you can set the Require applications to authenticate via API key slider to the off position so applications don’t need to authenticate when making API calls.

API key setting switched off

If you save this setting and then scroll down to the Sharing within Cloud Foundry organization and Sharing Outside of Cloud Foundry organization sections, you’ll notice that you are permitted to share the API both inside and outside your IBM Cloud org without needing to create an API key.

Sharing options with no API key

Exporting the API definition

From the API Info section, you can download the API definition as an OpenAPI document in YAML or JSON format, for import into an API management tool or REST client of your choice.

From the API Info section, expand the API definition drop-down list and then click either Export YAML file or Export JSON file. The file is downloaded to the default location configured for your browser.

Export YAML or JSON file

Join The Discussion

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