Win $20,000. Help build the future of education. Answer the call. Learn more

Use a serverless, event-driven architecture to run code that scales automatically


Are you looking for ways to use cloud resources efficiently and build and deploy applications more quickly?

Serverless, event-driven architectures can execute code that scales automatically in response to demand from a REST API. No code runs until an API call to an endpoint associated to a function is received by the API gateway.

Then application instances are started to match the load needed by each API request exactly.


The code in this repository implements a serverless REST API with IBM Cloud Functions. The REST API is a fully compliant implementation of the Todo-Backend API.

You can deploy it right away using an IBM Cloud Functions deployment script on your own system.

If you haven’t already, sign up for an IBM Cloud account and go to the Cloud Functions dashboard to explore other reference architecture templates and download command line tools, if needed.

The following components are used in this code pattern:

  • IBM Cloud Functions (powered by Apache OpenWhisk): Execute code on demand in a highly scalable, serverless environment.
  • Cloud Functions APIs (powered by Apache OpenWhisk): Define APIs that wrap a set of OpenWhisk actions.
  • The Cloudant service: Use a fully managed data layer designed for modern web and mobile applications that leverages a flexible JSON schema (powered by CouchDB).
  • The App ID service: Add authentication, secure back ends and APIs, and manage user-specific data for your mobile and web apps.

This application is a fully compliant implementation of the Todo-Backend API, with added authentication support.

It demonstrates using IBM Cloud Functions (based on Apache OpenWhisk) to build a REST API. The use case demonstrates how actions work with data services and execute logic in response to API requests. It also demonstrates how to secure the content behind the API using IBM App ID, by requiring an authentication token to access the API.

The authentication is terminated by the API Gateway, so functions do not need to worry about it. Functions receive the JWS token information from the API Gateway and can use it to add content authorisation rules. In this pattern authenticated users are connected to a dedicated Cloudant database, so that each user’s “to do” list is personal and persisted across sessions.

When you use this code pattern, you learn the following skills:

  • Use serverless functions to act as APIs for a simple “to do” list application, backed by Cloudant.
  • Easily add authorization to these APIs using the App ID service on IBM Cloud.



  1. When logging in, the user of the app obtains a token from IBM App ID authentication server. The App ID service verifies the user credentials against the cloud directory. The App ID service can also be configured to use different authentication providers.
  2. The App ID authentication service returns a JWS token to the user.
  3. An API request (HTTP GET) is issued from the user to the Cloud Functions API gateway to access the protected resource, including the JWS token.
  4. The Cloud Functions API gateway validates the token through the App ID service.
  5. The App ID service validates the token.
  6. The Cloud Functions API gateway invokes the function todo_get that is associated to the API endpoint and HTTP method.
  7. The function uses the JWS token to learn about the user requesting the resource and to select the content in the Cloudant database that the user is authorized to access. The function also builds the HTTP response and its JSON body with the requested “to do” item.


Find detailed technical steps for this code pattern in the file in the GitHub repository.

  1. Set up the account and credentials.
  2. Deploy through the deployment script.
  3. Verify it using the deploy script or verify it manually.