Creating a simple proxy API

This is my first blog entry ever, so excuse me if my style or cadence is awkward. My hope is that through this blog, I’ll be able to teach and learn from others about REST API patterns and best practices.

For this, my first post, I’ll use IBM’s API Connect in Bluemix to create a simple REST API that proxies calls to the Hacker News API. Oh, I forgot… disclaimers.

Disclaimer: I currently work at IBM. However, the views and opinions expressed in this blog are mine, and I am not in any way speaking on behalf of IBM.

Alright, disclaimers out of the way … lets get on with it. So, why am I choosing Hacker News API? It really does not matter.  It’s just for demonstration purposes. I need an API that can be easily invoked and does not have authentication. That’s all.

If you point your browser to, you get the JSON representation of the /v0/item/1 resource:

 "by": "pg",
 "descendants": 15,
 "id": 1,
 "kids": [
 "score": 61,
 "time": 1160418111,
 "title": "Y Combinator",
 "type": "story",
 "url": ""

That’s where I will be proxying to. Well, not to this specific resource, but more generally to: /v0/item/{id} , where {id} is a parameter passed by the end user.

Quick, go and sign up for a Bluemix account. Done? Now, login to Bluemix, navigate to Catalogs, and create an API Connect service.

Creating API Connect service in Bluemix

Next, within the API Manager user interface, navigate to Drafts, and select the APIs tab, and create a new API.

Creating API Connect service in Bluemix

Notice that on the creation dialog, I selected the option to create a new product. I’ll explain later why we need this “product”.

After creating the API, you are then taken into the API editor. This editor allows you to control how your API will look and behave. It has three views: Design, Source, and Assembly.

In order to understand how to work with the api editor, first you must understand some core concepts.

At its simplest, an API consists of two parts.

  1. The external interface
  2. The internal implementation

The external interface is like a contract between you (the creator of the API), and the clients who are going to consume it.

The internal implementation is what determines how the API behaves when a client invokes one of its resources.

In this blog entry, the API I am creating has a very simple interface. It consists of a single resource:


The internal implementation is also very simple. It’s just proxying the incoming call directly to the back-end Hacker News API.{id}.json



You may wondering how is this useful … since you can directly visit  the Hacker News API.  Here is the thing … big companies like airlines, banks, and retailers have a lot of interesting and useful services that they want to expose to developers out there. The problem is that these services are usually buried in private networks.

Using the on-prem or Bluemix dedicated version of API Connect, these customers are able to expose these internal services as nice REST APIs and make use features such as:

  • app API keys
  • Basic Auth
  • OAuth 2.0
  • rate limiting
  • usage analytics
  • Governance

Now, to create external interface of the API, I’ll add an operation with the “/hackernews/items/{id}” path within the Design view.


For the implementation part of this API, I’ll switch to the Assembly view and create a Proxy policy that invokes the back-end Hacker News API.



Notice that when editing the “URL” field of the proxy policy, instead of  using the exact url:

I used:$(

where the last segment is replaced by $( This is the notation used in API Connect for referencing parameters from the original client request.

This is it, the API is now technically done. I have specified the interface, and I have specified the implementation.

The next step is to test this API using the test tool in API Connect, then and make it public for people out there to consume it. I’ll cover this in the next blog post, and follow on with additional topics such as:

  • How to secure your API
  • How to do more complex assemblies involving multiple operations
  • Deep dive on how to use the mapper policy

I welcome your feedback in the comments. Tell me what you liked, or did not like, or if you have questions, etc.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s