How-tos

Getting started with the Bluemix API Management Service

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

Share this post:

Add Comment
23 Comments

Leave a Reply

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


Petr Dvořák

Guys, this is an absolutely great feature and we will jump into it as soon as we have a chance with our API. I would like to ask you couple questions for the future:).

1) Do you plan to add support for the “API Blueprint” format?
2) Will it be possible to select monetization options / prices for the API plans, so that we can use your platform as another revenue stream?
3) Will you include some streamlined process to move from “yet another custom API” to a standard Bluemix service? If yes, do you have some guidelines on how to get ready at this moment, so that we can make our APIs compliant?

Keep up the great work!

Reply

    Matt Roberts

    Hi Petr,

    Thanks for your questions, and I’m really pleased you are finding the API Management service useful!

    To answer your points;
    1) We are currently focused on Swagger as our description language. We do have some customers interested in some of the other languages like RAML and Blueprint, but for the time being Swagger seems to be the most popular and have the best ecosystem around it.
    2) Yes, monetization is something that we hear regularly from a range of customers so its a requirement we are actively discussing internally. It would be really useful if you can describe what you are looking for in this area so that we can understand your intended usage patterns and ensure the things we are looking at meet those requirements
    3) Providing the ability to publish your API as a conventional Bluemix service (rather than a “custom API”) is also something we are looking at currently. If you are describing your APIs via Swagger and managing them through the API Management service then that should put you in a good position for future improvements in this space

    Reply

      ANN LAMBRECHT

      Hi, is there any progress already in providing monetisation capabilities to API’s ? An API is published by a Bluemix customer, with a pay per use rate. IBM Bluemix is used for the billing towards the API-user. The Bluemix customer charges IBM with the rate minus X% ? Or what kind of functionality could be offered?

      Reply

joe_ross

Looking at security, I don’t see a way to specify that clients can pass a bearer token for current user in Authorization header. For example, if the client has already authenticated the user and has an OAuth access token with appropriate scope for the user. Is that planned?

Reply

    Matthew Hamann

    The article here focuses more on application identification than user authentication.

    That said, if OAuth isn’t turned on for the API, you could try passing the bearer token in the Authorization header and see what happens. Or, you can choose to enable OAuth on the API itself and use that mechanism within APIm to authenticate users.

    There are some enhancements coming in terms of OAuth, so stay tuned for those if the current capabilities don’t meet your needs.

    Reply

yuan

hi
when i was trying to add the service on the nodejs app , there displayed a error “Error retrieving plans data”.
any ideas to solve the error ?

Reply

    Matthew Hamann

    Currently, Bluemix is experiencing an issue causing some plan data not to load. A fix is in progress.

    As a workaround, you can use the `cf` CLI tool to provision and bind the service from the command line.

    Reply

      Anil

      Hi Matthew,
      I am unable to use the cf CLI tool, I need to know the service name of the Swagger Petstore.

      cf create-service “Swagger Petstore V1” “Pet Store – Gold Plan v1” “PetstoreAnil-wc”

      ce dev as anil.byalakere@in.ibm.com
      FAILED
      Service offering Swagger Petstore V1 not found

      Please help what should be name of the service.

      Thanks

      Reply

      Anil

      cf create-service “Swagger Petstore v1 : Sandbox 559d5ee50cf2afcd0288232a prod” “Pet Store – Gold Plan v1 : Sandbox prod” “PetstoreAnil-wc”

      Used above command then it worked,

      Thanks

      Reply

Cameron

How does an application deployed on cloud foundry exposing it’s api via api manager know what user/application is authenticated? And how does the cloud foundry app know that the call came via api manager and not directly from an unauthorised source?

Reply

    Matthew Hamann

    In addition to “identification” at the application level via a Client ID and Secret (if desired), API Management also supports either Basic authentication or OAuth.

    Take a look at the “Security” tab in the APIs section of the manager. There, you can configure the desired authentication mechanism, and even tie it back to your own application’s user API. There’s more info here: http://www-01.ibm.com/support/knowledgecenter/SSZFB2_3.0.1/com.ibm.apimgmt.apionprem.doc/con_apionprem_authentication.html

    If you’re less concerned with authentication and simply want to ensure that only calls through API Manager are accepted by your app, you could simply use the “assembly” mechanism in the APIs section to add a specific header with a default value to each API call. Your app could then check for this header, which would contain some secret key that only you know. Any requests without the header would be rejected.

    Hope that helps?

    Reply

howardy

Hi, when I was trying to [Step 4: Invite others to use your APIs (optional)] , there displayed a error “Could not send email because of an internal error. Check the server logs for more details.”.
any ideas to solve the error ?

Reply

    Matthew Hamann

    Hi Howard,

    There is currently a bug in the software pertaining to this specific feature. It will be fixed over the weekend and should be back in working order by Monday morning (9/7). Would you mind trying again at that point?

    Thanks!

    Reply

Mike Kistler

Trying to follow the steps in this tutorial. In Step 2, bullet 1, when I click on the “Import APIs, or compose a new one”, it sends me the Bluemix console home page — not the API manager. What did I do wrong? How do I get to the API manager?

Reply

    Mike Kistler

    Okay … looks like the “Import APIs …” link is broken, but the alternate path is not too hard to find. Just click on the big “GO TO API MANAGER” button at the bottom and the click on the “Compose APIs” icon in the left side button bar.

    Reply

Ricardo

Is there a list of updates to the service released on 11/17/2015 (last date service was published on Bluemix)?

Reply

Jaspreet Singh

Great article. Thanks.
This article is missing a key step which is to map implementation of APIs, without which it doesnt work at all.
This video talks about it …
https://youtu.be/sIm7Uq2PioI?t=14m54s

Reply

Sandeep Mishra

How to bring my own data from one cloud to IBM Bluemix cloud using API?

Reply

Salah

Hello,

Thanks for this tuto.

I’ve an issue. when I try to test the API via postman, I got : the below message :
****BINARY NODE****

Could you explain me what’s the problem ?

Thank you

Reply

Ilya

Do you have a REST API or some SDK to import swagger definition?

Reply
More How-tos Stories

Bluemix Private Catalog

With the Bluemix Private Catalog, delivered through our Cloud Integration service, developers in your organization can discover, bind and use your APIs as a service from the Bluemix Catalog. This articles shows the simple steps to * create an API from an on-premises database table * publish an API as a Private Service and * […]

Continue reading

Stop Password Fraud with Bluemix and aPersona

Stolen or weak passwords account for 95% of today’s data breaches. With password re-use at over 60%, you need to protect both your system admins AND your application users. aPersona makes it easy with their Adaptive Security Manager and BlueMix. Just four simple steps!

Continue reading

MobileFirst Quality Assurance (MQA) – crash capture, in-app testing, and app store analytics for iOS mobile apps (Part 3)

Does anyone care if their mobile app crashes? Mobile is everywhere and unfortunately so are app crashes! Sure it’s frustrating, but even more alarming is that the reputation and health of a business can blossom or crumble on the quality of its mobile channel. In the final installment of the three part series, you will see how to quickly harness public appstore feedback and act upon those issues before they become a larger social media problem. More…

Continue reading