Openwhisk web actions for API backends

An API is defined as an application programming interface which basically acts as a proxy between the backend service and the front end applications/users. We can depict the API’s role using the diagram below.

So as you can see for an API to act as a managed API it needs to have a backend service. In theory from what we know this backend service is something which would be hosted somewhere and made available at all times since we really do not know when requests would be coming through our API into our backend service. What if you needed your backend service to only be available when there are requests to be served? How can we facilitate this?

Why Serverless for API backends?

This is where the serverless architecture comes into the picture which uses a model where you only utilize the resources on demand. With serverless you no longer need to

• Worry about over capacity issues
• Pay for the time where your service is idle
• Worry about availability and reliability
• Worry about scaling.

When it comes to designing your serverless architecture based API backends, web actions are the best ways forward. Web actions are OpenWhisk actions annotated to quickly enable you to build web based applications. In other words we can refer to these as backend services which we can access with/without authentication based on our requirement.

Let’s create our API

In this tutorial I will be guiding you on how you can expose your web actions through the API gateway and ultimately use these web actions to act as your API backends. Let’s go through the steps of creating an API which maps to the web actions and how to effectively use it as an API.

For this tutorial we would be making use of the web actions we designed for some operations discussed in one of my previous posts. Follow the tutorial to create the mentioned web actions. What we would be trying to achieve is an API which maps to our web actions as depicted in the image below.

All our web actions are created under the library package. If we list the actions in our package now it should give us an output as below.

Now you are ready to go to the next step. We are going to build today a Library API which you need to expose.

Let’s create an API for the Library API name “LibraryAPI”, with /club as its HTTP URL base path and books as its resource and {isbn} as a path parameter used to identify a specific book by its ISBN.

An important thing one must note when defining path parameters with apis is that a response type of http is mandatory, By default it is set to JSON so it is very important to set it as http in this case.

Run the following commands in your openwhisk setup using the wsk CLI to create your Library API.

wsk api create -n "LibraryAPI" /club /books/{isbn} get library/getBooksAction --response-type http -i
wsk api create -n "LibraryAPI" /club /books/{isbn} put library/putBooksAction --response-type http -i
wsk api create -n "LibraryAPI" /club /books/{isbn} delete library/deleteBooksAction --response-type http -i
wsk api create -n "LibraryAPI" /club /books get library/getBooksAction --response-type http -i

Now you can list the api’s resources which we were created using the commands below.

wsk api list /club -f
ok: APIs
Action: library/getBooks
  API Name: LibraryAPI
  Base path: /club
  Path: /books/{isbn}
  Verb: get
  URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books/{isbn}
Action: library/getBooks
  API Name: LibraryAPI
  Base path: /club
  Path: /books
  Verb: get
  URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books
Action: library/putBooks
  API Name: LibraryAPI
  Base path: /club
  Path: /books/{isbn}
  Verb: put
  URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books/{isbn}
Action: deleteBooks
  API Name: LibraryAPI
  Base path: /club
  Path: /books/{isbn}
  Verb: delete
  URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books/{isbn}

Now let’s try invoking the different resources of our API through the API gateway and see the results.

Adding a new book

curl -X PUT https://${APIHOST}:9001/api/${GENERATED_API_ID}/books/harry-potter -k
{"message":"The book harry-potter was successfully added"}

Getting the details of a book

curl -X GET https://${APIHOST}:9001/api/${GENERATED_API_ID}/books/harry-potter -k
{"message":"Successfully retrieved the document","doc":"{\"_id\":\"harry-potter\",\"_rev\":\"7-8f8aeecee81c43e95dfa68c71c14c5fa\",\"description\":\"This is a sample book\",\"name\":\"harry-potter\"}\n"}

Deleting a book

curl -X DELETE https://${APIHOST}:9001/api/${GENERATED_API_ID}/books/harry-potter -k
{"message":"Successfully deleted the book harry-potter"}

Let’s sum it up

There you have it! We have successfully created an API with the web actions as the backend service and invoked our web actions which we exposed by our gateway APIs. To learn more capabilities about the Apache Openwhisk gateway you can refer this documentation. Hope this was helpful to understand the role of the api gateway in the Apache Openwhisk Serverless platform.

References

[1] https://medium.com/@shenavi21/openwhisk-web-actions-with-path-parameters-f8dc6e44846d

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

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