Using API Gateway with Serverless & OpenWhisk
As with all serverless offerings OpenWhisk offers an API Gateway to provide HTTP routing to your serverless actions. This provides a number of advantages over web actions, the most significant of which are routing based on HTTP method, authentication and custom domains (in IBM Cloud).
To route to an action using API Gateway, you first need to make your action a web action first:
$ wsk action update todo-backend/listTodos listTodos.php --web raw
(You can also use --web true, if you want the automatic decoding of post bodies and query parameters.)
Now that we have a web action we can create the API route:
$ wsk api create /todos GET todo-backend/listTodos --apiname todo-backed --response-type http
This creates the HTTP endpoint which is a massively long URL that starts with https:// and ends with /todos.
To create an API Gateway endpoint for an action, we add an http event to the action definition in serverless.yml:
The handler tells Serverless that the code for this action is in the main() function within listTodos.php and is required. We use the name parameter to set the package for this action (todo-backend.
Finally, to the list of events, we add a http section where we set following:
|path||The URL for the end point|
|method||The HTTP method for this end point|
|resp||The web action content type. Set this to http so that you can send back the status code and any custom headers|
If you use the http web action content type, you must return a dictionary with these three keys:
|statusCode||The status code (100-599)|
|headers||A dictionary of headers|
|body||The body content. If this is a dictionary, then it will be automatically converted to JSON for you.|
For example, in listTodos.php, we might have this:
* GET /todos
function main(array $args) : array
$container = new \App\AppContainer($args);
$mapper = $container[\Todo\TodoMapper::class];
$todos = $mapper->fetchAll();
'statusCode' => 200,
'headers' => [
'X-Clacks-Overhead' => 'GNU Terry Pratchett,
'body' => $todos->toArray(),
In this particular case, we don’t really need to set the statusCode as the default is 200 anyway. We also don’t need to set the Content-Type to application/json as this is also done for us as OpenWhisk has converted our array to JSON.
Adding API Gateway end points to an OpenWhisk API using Serverless is a few lines of configuration and then we can let the tool do the leg work of setting up OpenWhisk for us.