API Gateway

The “Hello World” API

This example builds on the “Hello World” Action example by adding an API definition on top of that action so that I can be queried via an HTTP call.

It shows how to:

  • update the Action named ‘hello_world’ to expose it to the gateway.
  • specify the API's endpoint that will trigger the action.

Manifest file

Example: “Hello world” action with API

packages:
  hello_world_package:
    version: 1.0
    license: Apache-2.0
    actions:
      hello_world:
        function: src/hello.js
        web-export: true
    apis:
      hello-world:
        hello:
          world:
            hello_world: GET

There are two key changes to this file:

  • the hello_world action now has the web-export flag set to true.
  • a new apis block has been created.

The apis block contains a number of groups of API endpoint. Each endpoint is then defined by the hierarchy. In this case, we are creating the hello/world endpoint. The leaf in the structure specifies the action to trigger when the given HTTP verb is sent to that endpoint, in this case, when the HTTP verb GET is used on the hello/world endpoint, trigger the hello_world action.

Deploying

You can actually deploy the “hello world API gateway” manifest from the incubator-openwhisk-wskdeploy project directory if you have downloaded it from GitHub:

$ wskdeploy -m docs/examples/manifest_hello_world_apigateway.yaml

Invoking

Check the full URL of your API first:

$ wsk api list

This will return some information on the API, including the full URL, which should end with hello/world. It can then be invoked:

$ curl <url>

Result

The invocation should return a JSON response that includes this result:

{
    "greeting": "Hello, undefined from undefined"
}

The output parameter ‘greeting’ contains “undefined” values for the ‘name’ and ‘place’ input parameters as they were not provided in the manifest or the HTTP call. You can provide them as query parameters:

$ curl <url>?name=World&place=Earth

Discussion

This “hello world” example represents the minimum valid Manifest file which includes only the required parts of the Package, Action and API descriptors.

Source code

The source code for the manifest and JavaScript files can be found here:

Specification

For convenience, the Packages and Actions grammar can be found here: