Creating a serverless application using the AWS CDK

This example walks you through creating the resources for a simple widget dispensing service. (For the purpose of this example, a widget is just a name or identifier that can be added to, retrieved from, and deleted from a collection.) The example includes:

An AWS Lambda function.
An Amazon API Gateway API to call the Lambda function.
An Amazon S3 bucket that holds the widgets.

This tutorial contains the following steps.

Create an AWS CDK app
Create a Lambda function that gets a list of widgets with HTTP GET /
Create the service that calls the Lambda function
Add the service to the AWS CDK app
Test the app
Add Lambda functions to do the following:
- Create a widget with POST /{name}
- Get a widget by name with GET /{name}
- Delete a widget by name with DELETE /{name}
Tear everything down when you're finished

Create an AWS CDK app

Create the app MyWidgetService in the current folder.

[ TypeScript ]

mkdir MyWidgetService
cd MyWidgetService
cdk init --language typescript

[ JavaScript ]

mkdir MyWidgetService
cd MyWidgetService
cdk init --language javascript

[ Python ]

mkdir MyWidgetService
cd MyWidgetService
cdk init --language python
source .venv/bin/activate
pip install -r requirements.txt

[ Java ]

mkdir MyWidgetService
cd MyWidgetService
cdk init --language java

You may now import the Maven project into your IDE.

[ C# ]

mkdir MyWidgetService
cd MyWidgetService
cdk init --language csharp

You may now open src/MyWidgetService.sln in Visual Studio.

Note
The CDK names source files and classes based on the name of the project directory. If you don't use the name MyWidgetService as shown above, you'll have trouble following the rest of the steps because some of the files the instructions tell you to modify aren't there (they'll have different names).

The important files in the blank project are as follows. (We will also be adding a couple of new files.)

[ TypeScript ]

bin/my_widget_service.ts – Main entry point for the application
lib/my_widget_service-stack.ts – Defines the widget service stack

[ JavaScript ]

bin/my_widget_service.js – Main entry point for the application
lib/my_widget_service-stack.js – Defines the widget service stack

[ Python ]

app.py – Main entry point for the application
my_widget_service/my_widget_service_stack.py – Defines the widget service stack

[ Java ]

src/main/java/com/myorg/MyWidgetServiceApp.java – Main entry point for the application
src/main/java/com/myorg/MyWidgetServiceStack.java – Defines the widget service stack

[ C# ]

src/MyWidgetService/Program.cs – Main entry point for the application
src/MyWidgetService/MyWidgetServiceStack.cs – Defines the widget service stack

Run the app and note that it synthesizes an empty stack.

cdk synth

You should see output beginning with YAML code like the following.

Resources:
  CDKMetadata:
    Type: AWS::CDK::Metadata
    Properties:
      ..."

Create a Lambda function to list all widgets

The next step is to create a Lambda function to list all of the widgets in our Amazon S3 bucket. We will provide the Lambda function's code in JavaScript.

Create the resources directory in the project's main directory.

mkdir resources

Create the following JavaScript file, widgets.js, in the resources directory.

/* 
This code uses callbacks to handle asynchronous function responses.
It currently demonstrates using an async-await pattern. 
AWS supports both the async-await and promises patterns.
For more information, see the following: 
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises
https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/calling-services-asynchronously.html
https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html 
*/
const AWS = require('aws-sdk');
const S3 = new AWS.S3();

const bucketName = process.env.BUCKET;

exports.main = async function(event, context) {
  try {
    var method = event.httpMethod;

    if (method === "GET") {
      if (event.path === "/") {
        const data = await S3.listObjectsV2({ Bucket: bucketName }).promise();
        var body = {
          widgets: data.Contents.map(function(e) { return e.Key })
        };
        return {
          statusCode: 200,
          headers: {},
          body: JSON.stringify(body)
        };
      }
    }

    // We only accept GET for now
    return {
      statusCode: 400,
      headers: {},
      body: "We only accept GET /"
    };
  } catch(error) {
    var body = error.stack || JSON.stringify(error, null, 2);
    return {
      statusCode: 400,
        headers: {},
        body: JSON.stringify(body)
    }
  }
}

Save it and be sure the project still results in an empty stack. We haven't yet wired the Lambda function to the AWS CDK app, so the Lambda asset doesn't appear in the output.

cdk synth

Create a widget service

Add the API Gateway, Lambda, and Amazon S3 packages to the app.

[ TypeScript ]

npm install @aws-cdk/aws-apigateway @aws-cdk/aws-lambda @aws-cdk/aws-s3

[ JavaScript ]

npm install @aws-cdk/aws-apigateway @aws-cdk/aws-lambda @aws-cdk/aws-s3

[ Python ]

pip install aws_cdk.aws_apigateway aws_cdk.aws_lambda aws_cdk.aws_s3

[ Java ]

Add the following dependencies in the dependencies element of your project's pom.xml file.

<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>apigateway</artifactId>
    <version>${cdk.version}</version>
</dependency>
<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>lambda</artifactId>
    <version>${cdk.version}</version>
</dependency>
<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>s3</artifactId>
    <version>${cdk.version}</version>
</dependency>

We recommend editing pom.xml directory rather than using your IDE's dependency management tools to make sure the versions of all AWS CDK libraries are synchronized using the $cdk.version variable.

[ C# ]

Choose Tools > NuGet Package Manager > Manage NuGet Packages for Solution in Visual Studio and add the following packages.

Amazon.CDK.AWS.ApiGateway
Amazon.CDK.AWS.Lambda
Amazon.CDK.AWS.S3

Tip
If you don't see these packages in the Browse tab of the Manage Packages for Solution page, make sure the Include prerelease checkbox is ticked.
For a better experience, also add the Amazon.Jsii.Analyzers package to provide compile-time checks for missing required properties.

Create a new source file to define the widget service with the source code shown below.

[ TypeScript ]

File: lib/widget_service.ts

import * as core from "@aws-cdk/core";
import * as apigateway from "@aws-cdk/aws-apigateway";
import * as lambda from "@aws-cdk/aws-lambda";
import * as s3 from "@aws-cdk/aws-s3";

export class WidgetService extends core.Construct {
  constructor(scope: core.Construct, id: string) {
    super(scope, id);

    const bucket = new s3.Bucket(this, "WidgetStore");

    const handler = new lambda.Function(this, "WidgetHandler", {
      runtime: lambda.Runtime.NODEJS_14_X, // So we can use async in widget.js
      code: lambda.Code.fromAsset("resources"),
      handler: "widgets.main",
      environment: {
        BUCKET: bucket.bucketName
      }
    });

    bucket.grantReadWrite(handler); // was: handler.role);

    const api = new apigateway.RestApi(this, "widgets-api", {
      restApiName: "Widget Service",
      description: "This service serves widgets."
    });

    const getWidgetsIntegration = new apigateway.LambdaIntegration(handler, {
      requestTemplates: { "application/json": '{ "statusCode": "200" }' }
    });

    api.root.addMethod("GET", getWidgetsIntegration); // GET /
  }
}

[ JavaScript ]

File: lib/widget_service.js

const core = require("@aws-cdk/core");
const apigateway = require("@aws-cdk/aws-apigateway");
const lambda = require("@aws-cdk/aws-lambda");
const s3 = require("@aws-cdk/aws-s3");

class WidgetService extends core.Construct {
  constructor(scope, id) {
    super(scope, id);

    const bucket = new s3.Bucket(this, "WidgetStore");

    const handler = new lambda.Function(this, "WidgetHandler", {
      runtime: lambda.Runtime.NODEJS_14_X, // So we can use async in widget.js
      code: lambda.Code.fromAsset("resources"),
      handler: "widgets.main",
      environment: {
        BUCKET: bucket.bucketName
      }
    });

    bucket.grantReadWrite(handler); // was: handler.role);

    const api = new apigateway.RestApi(this, "widgets-api", {
      restApiName: "Widget Service",
      description: "This service serves widgets."
    });

    const getWidgetsIntegration = new apigateway.LambdaIntegration(handler, {
      requestTemplates: { "application/json": '{ "statusCode": "200" }' }
    });

    api.root.addMethod("GET", getWidgetsIntegration); // GET /
  }
}

module.exports = { WidgetService }

[ Python ]

File: my_widget_service/widget_service.py

from aws_cdk import (core,
                     aws_apigateway as apigateway,
                     aws_s3 as s3,
                     aws_lambda as lambda_)

class WidgetService(core.Construct):
    def __init__(self, scope: core.Construct, id: str):
        super().__init__(scope, id)

        bucket = s3.Bucket(self, "WidgetStore")

        handler = lambda_.Function(self, "WidgetHandler",
                    runtime=lambda_.Runtime.NODEJS_14_X,
                    code=lambda_.Code.from_asset("resources"),
                    handler="widgets.main",
                    environment=dict(
                    BUCKET=bucket.bucket_name)
                    )

        bucket.grant_read_write(handler)

        api = apigateway.RestApi(self, "widgets-api",
                  rest_api_name="Widget Service",
                  description="This service serves widgets.")

        get_widgets_integration = apigateway.LambdaIntegration(handler,
                request_templates={"application/json": '{ "statusCode": "200" }'})

        api.root.add_method("GET", get_widgets_integration)   # GET /

[ Java ]

File: src/src/main/java/com/myorg/WidgetService.java

package com.myorg;

import java.util.HashMap;

import software.amazon.awscdk.core.Construct;
import software.amazon.awscdk.services.apigateway.LambdaIntegration;
import software.amazon.awscdk.services.apigateway.Resource;
import software.amazon.awscdk.services.apigateway.RestApi;
import software.amazon.awscdk.services.lambda.Code;
import software.amazon.awscdk.services.lambda.Function;
import software.amazon.awscdk.services.lambda.Runtime;
import software.amazon.awscdk.services.s3.Bucket;

public class WidgetService extends Construct {

    @SuppressWarnings("serial")
    public WidgetService(Construct scope, String id) {
        super(scope, id);

        Bucket bucket = new Bucket(this, "WidgetStore");

        Function handler = Function.Builder.create(this, "WidgetHandler")
            .runtime(Runtime.NODEJS_14_X)
            .code(Code.fromAsset("resources"))
            .handler("widgets.main")
            .environment(java.util.Map.of(   // Java 9 or later
               "BUCKET", bucket.getBucketName()) 
            .build();

        bucket.grantReadWrite(handler);
        
        RestApi api = RestApi.Builder.create(this, "Widgets-API")
                .restApiName("Widget Service").description("This service services widgets.")
                .build();

        LambdaIntegration getWidgetsIntegration = LambdaIntegration.Builder.create(handler) 
                .requestTemplates(java.util.Map.of(   // Map.of is Java 9 or later
                    "application/json", "{ \"statusCode\": \"200\" }"))
                .build();

        api.getRoot().addMethod("GET", getWidgetsIntegration);    
    }
}

[ C# ]

File: src/MyWidgetService/WidgetService.cs

using Amazon.CDK;
using Amazon.CDK.AWS.APIGateway;
using Amazon.CDK.AWS.Lambda;
using Amazon.CDK.AWS.S3;
using System.Collections.Generic;

namespace MyWidgetService
{

    public class WidgetService : Construct
    {
        public WidgetService(Construct scope, string id) : base(scope, id)
        {
            var bucket = new Bucket(this, "WidgetStore");

            var handler = new Function(this, "WidgetHandler", new FunctionProps
            {
                Runtime = Runtime.NODEJS_14_X,
                Code = Code.FromAsset("resources"),
                Handler = "widgets.main",
                Environment = new Dictionary<string, string>
                {
                    ["BUCKET"] = bucket.BucketName
                }
            });

            bucket.GrantReadWrite(handler);

            var api = new RestApi(this, "Widgets-API", new RestApiProps
            {
                RestApiName = "Widget Service",
                Description = "This service services widgets."
            });

            var getWidgetsIntegration = new LambdaIntegration(handler, new LambdaIntegrationOptions
            {
                RequestTemplates = new Dictionary<string, string>
                {
                    ["application/json"] = "{ \"statusCode\": \"200\" }"
                }
            });

            api.Root.AddMethod("GET", getWidgetsIntegration);

        }
    }
}

Tip
We're using a [lambda\.Function](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-lambda.Function.html) in to deploy this function because it supports a wide variety of programming languages. For JavaScript and TypeScript specifically, you might consider a [lambda\-nodejs\.NodejsFunction](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-lambda-nodejs.NodejsFunction.html). The latter uses esbuild to bundle up the script and converts code written in TypeScript automatically.

Save the app and make sure it still synthesizes an empty stack.

cdk synth

Add the service to the app

To add the widget service to our AWS CDK app, we'll need to modify the source file that defines the stack to instantiate the service construct.