APIful Blog We're obsessed with Web APIs


Introducing API Harmony Playground

Mar 29, 2017 •

Our goal with API Harmony is to be the best place to find, learn about, and use APIs. There is no better way to use and learn how APIs work than to play with the source code and see the results of API invocations.

We described how developers can use API Harmony to see not only API description but also how it is used. That capability is using “Big Code” analysis to synthesize lessons learned showing how API is actually used with links to Github source code and popular parameters and their values (for details see Learning How to Invoke IBM Alchemy Data News Through API Harmony.)

That still leaves developer with the task to copy source code to text editor, modify the code with lessons learned parameter values, pick an execution environment, and run snippet to see what the API returns. Would it not be great to just go to a page describing API such as IBM Alchemy Data News and be able to see the results of the API invocation with lessons learned parameters already included?

With API Harmony Playground this is possible now: click “Open in Playground” button and you can see the results of running a snippet code with lessons learned using serverless OpenWhisk in IBM Bluemix. If you provide IBM Bluemix OpenWhisk Authorization Key then you can modify the snippet source code and see the results immediately.

Let’s go through those steps in detail.

Walkthrough - screenshot

Go to API Harmony website, search for “news”, and click on IBM Alchemy Data News API.
Or go directly. You should see:

If you scroll down you should see the lessons learned parameter values.

Click on Open in Playground button.

Your browser should show now API Harmony Playground and the results of the snippet execution by OpenWhisk.

To be able to see the results after snippet code editting you need to setup OpenWhisk API Key, so the execution can be done on your behalk, don’t worry OpenWhisk gives you quite a few executions for free before they start charging. To do this click Setup button:

If you do not have Bluemix account you will need to sign up for free trial. Click link to https://console.ng.bluemix.net/openwhisk/cli and copy New Authentication to clipboard:

Go back to the playground and paste the authorization key. The first few letters of the key should be visible in upper right corner and you can now see results of code nippet execution as you type. Let’s add console.log("hello world"); to the snippet and see the output in the log:

If you have IBM Alchemy Data News API key (if not search Bluemix catalog for news and add Alchemy News service to your space to get the key) then edit snippet to use it:

The snippet is deployed as an OpenWhisk action that you can directly invoke using OpenWhisk REST API or edit it also in Bluemix UI using the OpenWhisk tools:

Here is a short video recording showing the scenario above:

Next steps

If you have any comments or suggestions for improvements please put them into comments below.

Share via a Tweet or follow us for everything APIs!