How-tos

Getting started with the Bluemix API Management Service

Share this post:

Bluemix API Management Service APIs are rapidly becoming one of an organization’s most important assets. Enabling customers and developers to consume APIs through their own applications and services provides a compelling system for innovation and monetization.

IBM API Management delivers a powerful mechanism for controlling API access, managing multiple versions of an API, establishing rate limits, and ultimately tracking the performance metrics and analytics of each API in your portfolio. Combined with Bluemix— IBM’s signature platform-as-a-service —we enable one-stop shopping and management of APIs from anywhere.

At InterConnect 2015, IBM launched the API Management service on Bluemix as a beta. Since then, we have been working diligently to improve the performance and stability of the service, and we are excited to announce the general availability of the API Management service on Bluemix.

Ready to try API Management?

If you’re new to our API Management tools, this video walks through the steps of this article:


Or if you want to try it yourself, this article will help you get quickly up to speed. Below are the steps you’ll follow:

  • Provisioning the API Management service on Bluemix
  • Creating and importing a new API
  • Publishing your APIs to the Bluemix catalog and sharing them with other Bluemix organizations
  • Consuming APIs from a Bluemix application.

You’ll need a Bluemix account for this tutorial. If you don’t have one already, sign up here!

Step 1: Provision the API Management service

  1. Open the Bluemix console and log in.
  2. Navigate to the catalog.
    Go to Catalog
  3. Select the Integration filter from the left-hand menu to reduce the number of displayed options, then locate and click the API Management tile.

    The service information page will appear.
  4. API Management presently offers a single “Standard” plan. This plan includes 5,000 free API calls per month, 1 free non-Bluemix developer portal account (developer portals are always included with Bluemix users), and 50MB of free storage space if you want to collect debug information and API analytics.

    Click the Create button to provision and launch the API Management service.

  5. The Getting started page will appear. If you’re new to API Management, we suggest following the steps listed. If you know your way around already, feel free to go directly to API Manager. You can check out the docs at any time by clicking Learn more.
    Getting started page

Step 2: Create your first API

The API Manager allows users to create APIs from scratch or import an existing API based on a Swagger or WSDL definition. For the purposes of this tutorial, we’ll be importing the Pet Store sample API via swagger.io.

  1. Click the Import APIs, or compose a new one link from the Getting started page in Bluemix. The API Manager will open in a new tab and may take a moment to load.
  2. Click the blue +API button, then select Import Swagger.
  3. Next, we can upload a Swagger document or reference one via a URL. For tutorial purposes, we’ll simply provide the URL to import. Paste the following URL into the Swagger URL field: https://raw.githubusercontent.com/mhamann/apim-sample/master/petstore.json. Leave the Username and Password fields blank, then click Load.
  4. API Manager will list all of the APIs and resources contained in the Swagger document. Click Add to create the API.
  5. The new API is now displayed in the API list. Click the API title to open the API editor.

    The API editor allows the modification of various API attributes. We can change the name, description, path, add and remove resources, and adjust options like authentication and authorization.
  6. Click the API path to edit it. Change it from /v2 to /petstore.
  7. Next, click the Security tab. Under the option “Identify Application Using,” select Client ID and Client Secret. Setting this option provides enhanced security for your API.

    Then, click Save API near the upper-right of the page.

The API has been created successfully.

Step 3: Create a plan

Every API must be part of a plan before it can be published and invoked. API Management uses plans to manage access to API resources, set rate limits, and stage APIs into various environments (e.g. a sandbox, test, production, etc). One plan may contain resources from any number of APIs, thereby enabling access to groupings of resources at varying rate limits. Later on, we’ll publish these plans for usage in Bluemix.

In this step, we’ll create a new plan, add our API resources to it, set rate limits, and deploy it.

  1. Open the Plans page by clicking the plans icon in the API Manager or by returning to the getting started page and selecting the next step.
  2. Click the + Plan button.
  3. Enter a name for the plan and click Add.
  4. The new plan will appear in the list. Click the plan’s title to open the plan editor.
  5. First, add the resources from the Pet Store API to the plan. Click the + Resource button.
  6. The list of APIs will appear on the left and the API’s resources on the right. If not already selected, pick the Swagger Petstore API, then select all of the resources that are part of the API. Then, click Add.

    The selected resources will appear in the lower portion of the plan editor.
  7. Next, set a rate limit for the plan. Rate limits may be set either individually for each resource -or- for the entire plan. If a rate limit is applied at the plan-level, it is applied to all of the resources in that plan.
    Set the rate limit for the plan by clicking the edit icon under the Rate limit section. Set the rate limit to: 10,000 requests per 1 Days. Then, click Apply.
  8. Click Save in the upper-right corner of the page to persist the changes to the plan.
  9. Finally, deploy the plan.
    Click the Deploy icon to display the deployment menu. Wait until the Sandbox option appears, then select it.

    After a few moments, a success notification should appear.

At this point, the plan has been deployed and is ready to be shared with others.

Step 4: Invite others to use your APIs (optional)

One of the core tenets of API Management is the ability to allow others to use your APIs. Pairing API Management with Bluemix enables APIs to be shared from one Bluemix organization to another. If you want to share an API with another organization, follow these steps, otherwise feel free to skip to step 5.

  1. Open the Developers page by clicking the developers icon in API Manager, or by returning to the getting started page and selecting the next step.
  2. Click the + Bluemix Organization button to invite a Bluemix user to associate their organization with yours. This simply enables you to share APIs with this organization in the future.
  3. Enter the email address of the person with which you want to share APIs, then click Invite.

    If this person is an existing Bluemix user, they must have the role of Manager or Billing Manager in their organization. If the person does not have a Bluemix account yet, they will be prompted to create one before proceeding.
  4. The invited user’s organization will not immediately display in the list of developer organizations. The user must check their email and accept the invitation before the new organization will appear.

Once the invitation process has been completed, proceed to step 5.

Step 5: Publish APIs to Bluemix

  1. Open the Management page by clicking the management icon in API Manager, or by returning to the getting started page and selecting the final step.

    The list of deployed plans will be displayed.
  2. Click the Pet Store – Gold plan to expand the plan and display the list of currently deployed versions.
  3. Click the icon to launch the plan publishing wizard:
  4. Ensure Publish this version is selected, then click Next.
  5. Ensure Select group of developer organizations and communities is selected, then enter or select Bluemix in the field below. If you invited another Bluemix organization back in step #4, you can also enter their organization name here to make the API available to them as well. (Note: if the entry field isn’t showing up right away, try clicking the blue circle next to the option “Select group of developer organizations and communities” even if it’s already selected.)
  6. Click Publish.

A notification should appear after a few moments indicating that the publish was successful.

Step 6: Bind the API to an app

We’ve successfully created our API in API Manager and published it to Bluemix. It will now show up in our organization’s Bluemix catalog. The final step in the process is to provision the API, bind it to an app, and watch the data flow!

For the purposes of this tutorial, we’ll create a new Node.js app and then provision and bind our API to it. (Any application type— not just Node.js —may be used to consume this API.)

  1. Open the Bluemix dashboard and click Create an app.
  2. Click Web.
  3. Click SDK for Node.js, then click the Continue button.

    Give the app a name, then click Finish. (This name should be unique, so be creative or just use your initials.)
  4. Once the app has been created, click the Overview section.
  5. Next, click Add a service or API. The Bluemix catalog will appear. Select the filter for Custom APIs on the left-hand sidebar, then click the Swagger Petstore tile to open the API details.

    Details about the API will be displayed, including all of the resources it provides, parameters, sample responses, and so on.<
  6. Notice, the app we created is already selected, so simply press the Create button to provision the API and bind it to the application. If you are asked to restage the application, click Restage. The Swagger Petstore is now bound to the application. We need only to test it and ensure that it works.
  7. Finally, let’s obtain the APIs credentials and test it out. On the left, click Environment Variables.

    The variables for VCAP_SERVICES should be displayed, which include the details for our Swagger Petstore API. Primarily of interest are the credentials, which contain the Client ID, Client Secret, and URL we need in order to invoke the API.

Step 7: Test the API

A tool like Postman may be used to test the API. We’ll demonstrate this here.

  1. Open the Postman utility or an equivalent.
  2. In the URL field, enter the URL like this:
    &lt;credentials.url&gt;/pet/findByTags?tags=tag1&amp;client_id=&lt;credentials.client_id&gt;&amp;client_secret=&lt;credentials.client_secret&gt;
    (Substitute the portions wrapped by < > with the appropriate value from your environment variable’s credentials.)

    In Postman, the setup looks like this:

  3. Click Send to execute the API request. If everything proceeds normally, the output should look something like this:

Congratulations! You’ve just set up a managed API, published it through a plan, and invoked it!

Authored by:
– Matt Hamann (@mhamann) – Software Engineer, Bluemix Cloud Integration
– Belinda Vennam (@BeeMarieV) – Software Development Manager, Bluemix Cloud Integration

Engineering Lead - API management services

More stories
April 19, 2019

Reach Out to the IBM Cloud Development Teams on Slack

Get the help you need fast—directly from the IBM Cloud Development Teams and other users on Slack.

Continue reading

April 19, 2019

Introducing IBM Cloud Object Storage Firewall: Further Secure Your Data

IBM Cloud Object Storage (COS) is giving you more control over who can access your data. We have introduced a new capability allowing you to configure your buckets with trusted IP address(es) that will dictate access to the data in COS.

Continue reading

April 18, 2019

Getting Started with IBM Cloud Databases for Elasticsearch and Kibana

In this article, we’ll show you how to use Docker to connect your Databases for Elasticsearch deployment to Kibana—the open source tool that lets you add visualization capabilities to your Elasticsearch database.

Continue reading