Hello World from API Gateway

This is a step-by-step guide for creating a simple serverless Web API using Lambda and API Gateway, and deploying it to AWS using Claudia.js. AWS Lambda is an event-driven compute service, that executes your code in reaction to various events. API Gateway is a HTTPS end-point that can receive requests and pass them on to Lambda. In this tutorial, we’ll connect them together to execute simple requests.


If you’re completely new to using AWS from Node.js, check out Installing and configuring Claudia.js for information on how to set up access credentials.

Initialising the project

Create a directory, and initialise a new NPM project, for example, using npm init. Make sure to give it a descriptive name.

Install Claudia.js in your global path:

npm install -g claudia

Although Claudia itself does not create any code dependencies for your projects, it comes with an optional helper that simplifies API Gateway set-up. The Claudia API Builder makes it easy to use API Gateway as if it were a simple JavaScript web server. Install it as a project dependency:

npm install claudia-api-builder -S

Creating a web endpoint

Your main API module should export an instance of claudia-api-builder. You can use the .get method to create a GET end-point. Similar functions exist for other HTTP methods. For now, we’ll just print out a simple static string. We’ll make that a bit more dynamic later.

Create app.js with the following code:

var ApiBuilder = require('claudia-api-builder'),
  api = new ApiBuilder();

module.exports = api;

api.get('/hello', function () {
  return 'hello world';

Deploying to AWS

You can now send your new API to the AWS cloud. Instead of setting the handler method, such as when creating a plain Lambda function, you’ll need to provide the name of the main API module using --api-module. Because the file with the code is app.js, the main module will be just app. Run the following command:

claudia create --region us-east-1 --api-module app

In a few moments, Claudia will respond with the details of the new Lambda function and REST API, looking similar to the one below:

  "lambda": {
    "role": "test-executor",
    "name": "test",
    "region": "us-east-1"
  "api": {
    "id": "8x7uh8ho5k",
    "module": "app",
    "url": "https://8x7uh8ho5k.execute-api.us-east-1.amazonaws.com/latest"

The result will contain the root URL of your new API. We created an endpoint for /hello, so just add /hello to the URL, and try it out in a browser or from the console. For example, execute:

curl https://8x7uh8ho5k.execute-api.us-east-1.amazonaws.com/latest/hello

(replace the API URL with the one you got from the deployment result).

You should see the ‘hello world’ response – and your first serverless API is now live in the cloud!

Using request parameters

Let’s make the API a bit more dynamic. Claudia API Builder provides an object to your request handlers with all the query string and form parameters, dynamic path component information and environment variables, so you can easily use them without creating any API Gateway template mapping files. Try this next:

Install the superb module as a project dependency:

npm install superb --save

Add a new endpoint to the API by appending these lines to your api.js:

api.get('/greet', function (request) {
  var superb = require('superb');
  return request.queryString.name + ' is ' + superb.random();

You can send the new version of your API to AWS simply by running the following command:

claudia update

When the deployment completes, try out the new endpoint by adding `/greet?name=’ followed by your name. You’ll get a nice confidence boost.

$ curl https://8x7uh8ho5k.execute-api.us-east-1.amazonaws.com/latest/greet?name=Mike
"Mike is fantastic"

Where next

Check out the other Tutorials for more advanced guides.

API Builder allows you to control almost anything you’d expect from a lightweight web server, including setting custom response headers, controlling response codes and content types, intercepting requests and more. Check out the API Documentation for information on how to do that.

Did you like this tutorial? Get notified when we publish the next one.

Once a month, high value mailing list, no ads or spam. (Check out the past issues)