IBM Bluemix OpenWhisk REST API

IBM recently announced event driven application execution environment called OpenWhisk. This is what we can find from the page.

OpenWhisk provides a distributed compute service to execute application logic in response to events.

Event driven programing are used for a long time, especially in designing application (both client native and web application). For example, user clicked mouse, user input text, so on. Programing model normally use event handler to handle those event. Likewise, the needs to handle internet events are rapidly growing. Mostly, the rise of internet of things (IoT) are overwhelming around us.

These things ( including human ) produce events, such as location changes, temperature changes in case of sensor devices. In case of human, they produce text or pictures in SNS timelines. These also can be thought as events on the internet.

IBM Bluemix provides a service called IoT Foundation for IoT devices, and Message Hub for general purpose event store or broker. However these service do not provide so called “Event Handler” as is. OpenWhisk is a solution for it. The OpenWhisk also is designed to popular “server less” style favor developers, since it accept single purpose code, and immediately runs on the cloud. This is sometimes called “microservice” type application because it provides single purpose business.

OpenWhisk project itself has good tutorial on how to run code on IBM Bluemix OpenWhisk platform. If you are not familiar with this technology, I recommend to run tutorial found in Bluemix document for OpenWhisk.

This blog is intended to provide additional information, “how to run REST API” against IBM Bluemix OpenWhisk. The REST API document may come soon. But early adapter may want to try first like myself, since I was the one who loves microservice architecture.

Calling REST API via “curl”

The API endpoint at the time of writing is this:

https://openwhisk.ng.bluemix.net/api/v1

And to call API, the following header must be set.

Content-Type: application/json
Authorization: Basic <based64 encoded key>

The <base64 encoded key> is a base64 encoded Authorization Key. If you run tutorial, this is set via “wsk property set” command. base64 encodeing can be done like:

$ wsk property get --auth | awk '{printf("%s", $3)}' | base64 --wrap=0

I have put these values as TYPE and AUTH environmental variable. I also put my name space in NAMESPACE environmental variable.

$ export TYPE='Content-Type: application/json'
$ export AUTH='Authorization: Basic '`wsk property get --auth | awk '{printf("%s", $3)}' | base64 --wrap=0`
$ export NAMESPACE=<my-name-space>

REST API are documented in swagger API (Bluemix, OpenWhisk). For example, if I want a list of actions, call “<api-end-point>/namespaces/<namespace>/actions” will show us a list of them.

$ curl -s -X GET -H "$TYPE" -H "$AUTH" https://openwhisk.ng.bluemix.net/api/v1/namespaces/$NAMESPACE/actions | jq ".[] | .name"
"weather"
"hello"

I got actions “weather” and “hello” which I have created by executing tutorial. “jq” command is used to filter JSON object. In this case, it shows name of actions. To execute an action,  call <api-end-point>/namespaces/<namespace>/actions/<action-name> with POST method. Data must be provided in json format if action requires parameters.

$ curl -s -X POST --data '{"location": "kyoto"}' -H "$TYPE" -H "$AUTH" https://openwhisk.ng.bluemix.net/api/1/namespaces/$NAMESPACE/actions/weather?blocking=true | jq '.response.result.msg'
"It is 10 degrees in kyoto and Partly Cloudy"

I have supplied “?blocking=true” parameter to obtain the result immediately. This is equivalent to specify “-b” option in “wsk action invoke” command.

Calling REST API within Node.js application

Calling this REST API from application should be straight forward. For example, I can write to call API like this:

    var result;
    var apihost = WhiskApi.host;
    var apipath = WhiskApi.path + "/actions/" + action + "?blocking=true";
    var opts = {
        host: apihost,
        path: apipath,
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': apiKey
        }
    };

    // https request to Whisk 
    var req = https.request(opts, function(res) {
        var output = '';
        res.on('data', function(chunk) {
            output += chunk;
        });
        res.on('end', function() {
            result = JSON.parse(output);
            callback(result, null);
        });
    });

    // Send request body : action parameters.
    req.write(JSON.stringify(param));
    req.end();

First, set the options to pass to “https.request()” method, and then wait for response.

I wrote sample web application, it worked very well. 🙂

whisk-demo-web-app

So I was able to add “weather” feature to my web application very easily. This is good part of OpenWhisk feature as microservice.

 

Advertisements
This entry was posted in Bluemix. Bookmark the permalink.

5 Responses to IBM Bluemix OpenWhisk REST API

  1. Pingback: developerWorks Open | Plan your conference schedule with a serverless OpenWhisk recommendation bot | developerWorks Open

  2. Peter says:

    I am on the Mac. –wrap=0 option doesn’t work for me. What should it be?

  3. Peter Tuton says:

    The baseURL requires “/v1/” (instead of “/1/” for the kyoto example… Thanks for the write-up.

  4. Pingback: 在Bluemix 使用OpenWhisk & Node-red 開發Event-Driven 應用系統 – slimchenblog

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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