Openwhisk Web actions with path parameters

What are web actions?

Web actions can be explained as OpenWhisk actions annotated to quickly enable you to build web based applications as defined in the official documentation. If we compare an Openwhisk action and a web action, an OpenWhisk action that is not a web action requires both authentication and must respond with a JSON object. In contrast a web action can be invoked even without authentication and is capable of also passing additional data such as HTTP header, Status codes and returning body content of different types.

What can we retrieve inside a web action?

When invoking web actions they are capable of receiving additional HTTP request details as they are designed to facilitate features of HTTP invocations.

• __ow_method : The HTTP method of the request.
• __ow_headers : The request headers.
• __ow_user: The namespace identifying the OpenWhisk authenticated subject who created this web action.
• __ow_path:The attributes which are passed as path parameters into the action.
• __ow_query:The parameters which are passed into the action as query parameters.
• __ow_body:The request body entity, as a base64 encoded string when content is binary or JSON object/array, or plain string otherwise.

We will be making use of such attributes in the web actions we are going to create in this tutorial in order to build up meaningful web actions.

Let’s get started with our web actions.

We are going to create some web actions which carry out some basic CRUD operations on a database. For this example we will be making use of a library database which store information about books which we are going to create in the inbuilt couch database installation.

Make sure you have an installation of apache openwhisk to proceed with this tutorial. If you do not have one you can simply create it by following this guide.

1. Creating the database: We would be creating a database in our couch database which comes with the openwhisk setup. Execute the below command in your setup to create a database named library-database.

curl -X PUT "http://172.17.0.1:5984/library-database?n=3&q=8" --user <Couch db username>

• * You can find your couch db username and password in the file openwhisk_home/ansible/db_local.ini file

2. Creating the web actions:

1. To create the web action you need to checkout the code from github. Let’s name this checkout as web-actions-samples
2. Navigate to the location web-actions-samples and open the file named as installLibraryActions.sh
3. Provide your couch database URL and the database name. In our case the database name would be “library-database” and by default in a local installation the couch database URL would be http://172.17.0.1:5984.
4. Next install the web actions by running the script. This will install three web actions inside a package called library

./installLibraryActions.sh

ok: updated package library
updating: getBooksAction.js (deflated 78%)
updating: dbUtils.js (deflated 75%)
updating: package.json (stored 0%)

ok: updated action library/getBooksAction
updating: putBooksAction.js (deflated 72%)
updating: dbUtils.js (deflated 75%)
updating: package.json (stored 0%)

ok: updated action library/putBooksAction
updating: deleteBooksAction.js (deflated 74%)
updating: dbUtils.js (deflated 75%)
updating: package.json (stored 0%)

ok: updated action library/deleteBooksAction

3. Verifying the web actions : Now let’s make sure that the web actions have been successfully created in the system. For that let’s list the web actions which are under the library package by running the command below.

wsk package get --summary library -i

package /guest/library: This package manages the library API backend actions
   (parameters: *dbName, *dbUrl)
 action /guest/library/deleteBooksAction
   (parameters: none defined)
 action /guest/library/putBooksAction
   (parameters: none defined)
 action /guest/library/getBooksAction
   (parameters: none defined)

4. Invoking the web actions: Before we invoke the web action we need to get the web url which corresponds to the action we just created. For that let’s run the command below which would return us with the web url.

wsk action get library/putBooksAction --url -i

ok: got action putBooksAction
https://172.17.0.1/api/v1/web/guest/library/putBooksAction

Now that we have the URL we can simply invoke this web actions using the PUT HTTP method.

curl -X PUT -k https://172.17.0.1/api/v1/web/guest/library/putBooksAction/books/harry-potter

{"message":"The book harry-potter was successfully added"}

You can verify that this was added into your database by simply retrieving the details of the book. Make sure you get the url of the getBooksAction in the same way you retrieved the putBooksAction mentioned above to get the details of the book we just created.

curl -X GET -k https://172.17.0.1/api/v1/web/guest/library/getBooksAction/books/harry-potter

{"message":"Successfully retrieved the document","doc":"{\"_id\":\"harry-potter\",\"_rev\":\"9-9bbdeb76e82ae8296afeb3fe2e7b3ef2\",\"description\":\"This is a sample book\",\"name\":\"harry-potter\"}\n"}

As you can see in the above example we invoked this action with a path parameter in the format /books/{book-name}. How did our action correctly handle this request? It’s pretty simply. If we open up the code of the action file “putBooksAction.js” which was used to create the putBooksAction we can see a logic which handles the matching of path parameters and HTTP methods using the HTTP attributes embedded into a web action as described above. The web action receives these information at the time of the invocation.

If we log the args object passed into our web action we can see the following information. You can see things like the method and path etc.

{
   "dbUrl":"http://172.17.0.1:5984",
   "dbName":"library-database",
   "__ow_method":"get",
   "__ow_headers":{
      "host":"controllers",
      "user-agent":"curl/7.47.0",
      "accept":"*/*"
   },
   "__ow_path":"/books/harry-potter"
}

In our action code logic we have used web action attributes of the object passed into the web action during the invocation. args.__ow_path, args.__ow_method to route to the correct database operations. With this we then facilitate our web actions to be used with path parameters with different HTTP methods. Likewise we can extend this to use query parameters or act upon various requests payloads as well. The flexibility lies in our hands when creating our web actions to meet our service requirements.

Read more about web actions and their capabilities in the official documentation on web actions. Hope this post has helped you to get an understanding on how to write web actions which consists of path parameters and various HTTP methods.

References.

[1] https://github.com/apache/incubator-openwhisk/tree/master/ansible

[2] https://github.com/Shenavi/Blog-Samples.git

[3] https://github.com/apache/incubator-openwhisk/blob/master/docs/webactions.md