Tech Blog

Leveraging the Public Cloud: Building a Serverless API

Often when building apps for our users there is a need to host a back-end API. Public cloud offerings make hosting APIs easy and affordable. In a previous post, we used the services of the AWS public cloud to host an API. In this post, we’ll learn how to use the AWS API Gateway and Lambda serverless functions to build and deploy an API in a few steps. This flexibility allows us to provide services to our own apps (stand-alone or Cloud Apps) easily and for little or no cost.

Our goal is to implement a use case needed by developers for a live Alma institution – to provide the ability to take a Chinese character string and convert it into its pinyin Latin-character transliteration. A quick search of the web reveals that there is an NPM library called “hanzi-to-pinyin” which handles this functionality. Our goal is to wrap this library in a serverless API so that we can use its functionality from other applications. “Serverless computing” is the methodology by which we use on-demand resources from a cloud provider, without the need to provision servers or other infrastructure.

AWS provides a framework called “SAM”, or “Serverless Application Model“, along with a CLI that facilitates development of serverless functions on a local workstation and deployment of the function to the AWS cloud. To fully follow along with this scenario, you can install the AWS CLI and the SAM CLI. (There are getting started guides and tutorials available online if you’re interested in learning more.)

Run the Function Locally

The code for our serverless hanzi-to-pinyin wrapper is located in this Github repository. We first clone the repository locally by running

$ git clone
$ cd pinyin-sam

Then we install the dependencies and start the application by running:

$ npm install
$ npm start

The start script uses the SAM CLI to run a local version of the Lambda function environment. Once the environment starts up, we can visit http://localhost:3000/pinyin/我的猫喜欢吃苹果 in a browser to confirm it’s working.

Deeper Look

Let’s take a deeper look at what makes this work. The app is made up of the following directory structure:

├── dependencies
│   ├── lib
│   │   └── cedict_db
│   └── nodejs
│       ├── package-lock.json
│       ├── package.json
│       └── postinstall.js
├── package-lock.json
├── package.json
├── src
│   ├── app.js
│   └── utils.js
└── template.yaml

The src folder contains the function logic, which exposes a handler. The handler accepts the text from the URI and runs it through the convert function of the hanzi-to-pinyin library, and prepares the response. The dependencies folder includes the Node libraries and a folder for the built-in transliteration dictionary.

The template.yaml file defines the cloud resources that we want to create. There are two resources- our function (in the src directory) and the dependencies in a Lambda layer (in the dependencies directory) which helps separate the libraries from our code. The use of the template file follows the “infrastructure as code” methodology which provides predictable, repeatable results.

Deploying the API

We use the aws CLI to package and deploy the API and dependency layer to AWS. As specified in the repository’s README file, we need to create a .npmrc file which contains some environment variables, including an AWS S3 bucket located in our AWS account in which to place the zipped artifacts (code, dependencies). The CLI commands are wrapped in the NPM package scripts, so we can simply do the following:

$ npm run deploy

Uploading to sam/c6cefcf478665841b96cd706859b6122  19743137 / 19743137.0  (100.00%)
Successfully packaged artifacts and wrote output template to file template.packaged.yaml.

Waiting for changeset to be created..
Waiting for stack create/update to complete
Successfully created/updated stack - PinyinApi

|                                          DescribeStacks                                          |
|  Description |    Key     |                                Value                                 |
|  Endpoint URL|  PinyinApi |  https://**********   |

The output provides us with the URL of our newly created API. You can use this URL in a browser to test that it’s working as expected.

To remove the resources, we can run npm run delete-stack.

Putting it Together

You can use this pattern to package and deploy your own API for your requirements. The video below shows the whole process described above, including using the newly created and deployed API in a Cloud App. Hope this is helpful in your use cases!

Leave a Reply