API Connect has many features that make developing and publishing APIs a rapid experience, but what if you already have an API? Good news — API Connect makes it easy to define, manage, and leverage existing APIs, too.

In this example, we’ll use the GitHub API to show how quickly you can get started creating and testing APIs with API Connect on Bluemix.

Required Ingredients

  • A pre-existing API (For this example, we will use endpoints from GitHub’s API: https://api.github.com)
  • A free Bluemix trial account (Don’t have one? Sign up here.)
  • A provisioned API Connect Essentials plan in Bluemix (free for < 50,000 API calls/month)


If you haven’t done so already, create a catalog in your API Connect Dashboard by clicking the ‘Add’ button in the upper left corner. The catalog will allow you to organize your APIs and manage access later.

Draft Your API

Next we will want to open the drafts panel by clicking the double right facing chevrons next to the house in the upper left corner. This will open our navigation menu which we will use extensively throughout this article. When the panel opens click “drafts” to move to the Drafts page.

This video provides a quick rundown of the steps (create, design, assemble, test) I will be go through in more detail below:


Now we need to create an API definition. Select APIs and then click the add button again in the upper left. Select new API, and fill out the form that pops up next. A few items to note:

  • The “Base Path” is important as it sets the starting point for the request.path property that we can use when designing our API. We will look more into request.path and context variables later. Leave it empty.


Once you create the API, you can start defining its features in the “Design” view. There is a lot here so we will stick to the basics of creating and manipulating paths. Click “Paths” in the left navigation bar. Then click the plus sign on the right to create a new path.

Paths help to build the request.path variable. Define a path called “/organizations” to correspond to the organizations resource on https://api.github.com. An HTTP GET method will be added for this path automatically, but you can specify any HTTP verb you would like and add multiple verbs as well. The gateway will use the combination of a verb and path to choose the corresponding action to execute.

Save the design by clicking the diskette in the upper right hand corner.


Click “Assemble” to head over to the API Assembler. Click the invoke statement and change the $(target-url) to https://api.github.com. $(request.path)-- the “context variable” mentioned earlier– will be a concatenation of our base path and the path of our specific request (in this case: /organizations). Now, any time we call the /organizations route on our gateway it will call to https://api.github.com/organizations.

Save the assembly by hitting the diskette in the upper right. Now hit the right facing arrow above the central assembly screen and we can test our API.


Hit the “Republish product” button to refresh the API definition in the gateway. This publishes the API into a default product and the default catalog, Sandbox.

Select the “GET /organizations” operation and then hit the blue invoke button at the bottom.

Try It Out (It’s Free)

Ready to start drafting your own APIs? API Connect Essentials is free for up to 50,000 API calls a month. Sign up for a free trial of Bluemix to get started.

Additional Resources:
Managing the API product’s life cycle
Setting up an advanced API assembly flow

Join The Discussion

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