Invoking actions on the IBM Cloud Functions platform

You've deployed code to IBM Cloud from the developerWorks sandbox. Now what?


Interactive code: When you see Run at the top of a code sample, you can run the code, check the results, make changes, and run it again. When you see Deploy, you can deploy the code into the developerWorks IBM Cloud account.

This article shows you four ways to access an action in the IBM® Cloud Functions environment once you've deployed code to IBM® Cloud via the developerWorks sandbox. IBM Cloud Functions run on top of OpenWhisk, so we'll start by looking at the basics of OpenWhisk before we talk about how to use your newly deployed code.

OpenWhisk basics

OpenWhisk is an open-source platform for serverless computing. The main idea behind serverless computing is that it's wasteful to spin up a virtual machine that does nothing more than host a small piece of code that is invoked occasionally. First of all, it's financially wasteful because you're paying for that VM to be up and running 24/7 when it's idle the majority of the time. It's also wasteful because you have to spend your time maintaining the software running in that VM. You have to patch the operating system, you have to patch the infrastructure, and you have to patch the language runtimes. Finally, if your code does something important, you have to make it fault-tolerant and scalable, incurring more costs as your server-based architecture gets larger and more complicated.

Enter serverless computing. With OpenWhisk, you don't create a server to run your code, you give your code to the system and define the conditions (triggers and rules, in OpenWhisk parlance) under which your code should be executed. When one of those conditions occurs, the OpenWhisk runtime runs your code. You're charged per invocation, not per hour. If your code is invoked only occasionally, serverless computing is far less expensive. And, any required infrastructure maintenance is done by the IBM Cloud team. That's the beauty of the IBM Cloud OpenWhisk environment.

Cloud Functions / OpenWhisk concepts

The Cloud Functions platform uses several types of OpenWhisk resources. Although actions are the only type we'll use in this article, it's important to understand these concepts:

  • Actions: An action is the code that is executed. It does some typically short-lived task, then it terminates and the code becomes dormant. An action takes a JSON object as its input and returns a JSON object as its output. Again, the code you deployed in the developerWorks sandbox is a Cloud Functions action.
  • Triggers: A trigger is a name associated with a class of events. A user can fire a trigger directly or a trigger can be fired by the Cloud Functions platform in response to an event from a feed. And speaking of feeds...
  • Feeds: A feed connects an external event source (something outside the Cloud Functions platform) to a Cloud Functions trigger. For example, you could create a feed of changes to a Cloudant database, then tie the feed and a trigger together. That would cause the trigger to fire every time the database changed.
  • Rules: Rules tie triggers and actions together. When a trigger fires, a rule determines what actions should be invoked as a result. You can define a rule to invoke multiple actions, and you can have multiple rules invoke the same action.

This picture illustrates the relationship among the four concepts.

OpenWhisk architecture

OpenWhisk architecture

Those are the basics of how the Cloud Functions platform works. If you want to go beyond the basics we'll cover here, knowing these concepts is crucial. That being said, all we're going to do here is use the Cloud Functions platform to invoke an action directly. We won't use feeds, triggers, or rules; we'll simply call our action. (The IBM Cloud documentation includes a great overview of the IBM Cloud Functions platform and how it works.)

Our sample action

The sample action we'll use in this article is a simple Hello World action. That code takes as input a JSON object containing a name and returns another JSON object with a personalized greeting.

To get things started, click the Deploy button below to, well, deploy this code:

Show result

The URL returned by the sandbox is the address of the Cloud Functions action. Copy it to the clipboard if you want; we'll be using that address throughout this article. (Note: the URL that's generated is unique for you, so what you'll see will be different from the examples here.)

We'll look at four techniques for invoking the action:

  • Using a browser-based HTTP tool
  • Using the curl command-line tool
  • Using the npm request package inside a node.js application
  • Using the HttpURLConnection class inside a Java application

Method 1: Using a browser-based HTTP tool

The first technique we'll use is invoking the Cloud Functions action from a browser-based tool like the Advanced REST Client for Chrome. There are similar tools for other browsers. Regardless of the tool you use, there are four basic things you need to know or specify:

  • The URL of the action - this is the URL from the sandbox above.
  • The HTTP verb must be POST.
  • The request needs a Content-Type HTTP header with a value of application/json.
  • The value for name inside a JSON object.

To get started, paste the URL from the developerWorks sandbox into the URL field:

Pasting in the URL

Pasting in the URL

Next, make sure the POST radio button is selected, then click the second drop-down menu. Select application/json from the menu:

This is a POST request with a content type of application/json

This is a POST request with a content type of application/json

The next thing to do is to fill in the content with the name field. The content is a JSON string, so make sure your syntax is correct.

The content to send to the service and the button that sends it

The content to send to the service and the button that sends it

With all of the details filled in, click the SEND button. You should see results like this:

The data returned by the OpenWhisk action

The data returned by the OpenWhisk action

In this simplistic example, the action returns a simple greeting. As an exercise for the reader, try deploying a more complicated sample such as the one illustrated in the article Translate natural language with the Watson Language Translator service. (Be aware that using the Language Translator service requires you to define credentials in your IBM Cloud account. You also need to create a more complicated JSON object. See the article for complete details.)

Method 2: Using the curl command-line tool

The curl command-line tool is a common way of interacting with resources on the web. Just as with the Advanced REST Client, we have to define various properties and parameters. All of those are done on the command line. Again, those are:

  • The URL of the action - this comes from the developerWorks sandbox when you deploy the code.
  • The HTTP verb must be POST.
  • The request needs a Content-Type HTTP header with a value of application/json.
  • The value for name inside a JSON object.

Given the service from the previous example, the curl command looks like this:

curl [the URL from the sandbox] -X POST -H "Content-Type: application/json" -d '{"name": "Susan"}'

-X POST specifies that this is an HTTP POST operation, the -H (header) flag defines the Content-Type header, and the -d (data) flag contains the information that is passed to the action. The JSON structure is returned to the command line. (If you'd like the output written to a file, add the -o option and specify a filename.)

Method 3: Using the npm request package inside a node.js application

The next approach we'll consider is using the npm request package to invoke the action as part of an application. By invoking an action as part of an application, you can use Cloud Functions actions as microservices. (Microservices are discussed briefly in an excellent introduction to serverless computing on Martin Fowler's blog.)

Here's a short node application that invokes the action we've referenced throughout this article. Replace [URL] with the URL of the deployed Hello World code. Click the Run button to run the code:

Show result

The options object contains the URL of the action, the input data (the body), it sets the Content-Type header, and it tells the request object that the data being sent to the action is JSON.

With the options and the callback function defined, we use to send the data to the action with the appropriate data and headers. Running this node application generates these results:

Hello, Susan!

The call to console.log() prints the greeting field from the JSON object returned by the action. For many actions you'll need to inspect a more complicated JSON object to find the data you need, but here we're keeping it simple.

Method 4: Using the HttpURLConnection class inside a Java application

The next approach we'll consider is using the HttpURLConnection class in a Java application. As you'll see, this requires the same information used in all the other ways of invoking the action, they're just defined and specified with different syntax. As with the node.js version, replace [URL] with the URL of the action and click the Run button to run the Java application below:

Show result

This code generates these results:

  "greeting": "Hello, Susan"


We've covered four different ways to invoke an action in the IBM Cloud Functions platform. Although these examples used an action deployed with the developerWorks sandbox, these techniques work with any action, no matter how it was deployed. If you use the IBM Cloud console to deploy actions to your own account, you can use the very helpful wsk command-line tool to invoke, manage, and monitor any Cloud Functions resources you've defined, including actions, triggers, and rules.

We encourage you to expand your knowledge of IBM Cloud Functions (and OpenWhisk) by working with it in your own IBM Cloud account. A good place to start is the article Build a user-facing OpenWhisk application with IBM Cloud and Node.js. You can also visit the OpenWhisk developer center for a more general resource. Enjoy the power and flexibility of serverless computing!

Downloadable resources


Sign in or register to add and subscribe to comments.

Zone=Web development
ArticleTitle=Invoking actions on the IBM Cloud Functions platform