doc

README

AWS SAM Golang Example

An example API and Worker written in Golang using the Amazon Serverless Application Model (AWS SAM).

Overview

Go is arguably one of the easiest languages in which to write a RESTful API. With the addition of Go support for AWS Lambda coupled with the maturity of tooling around the AWS Serverless Application Model, deploying Golang-based APIs to serverless infrastructure is becoming much more straightforward, too. Thanks to the APEX Gateway, you can even write APIs in a familiar manner without changing how the code is structured.

The purpose of this project is to give a slightly more complicated example than the "hello world" ones provided by Amazon with a toolchain that supports both local development and deployment to AWS as well as design patterns that facilitate unit testing.

Prerequisites

• An AWS account
• Golang
• Docker
• Node.js
• AWS Command Line Interface
• SAM CLI
• jq (optional)

Installation

With a correctly configured Go toolchain:

go get github.com/cpliakas/aws-sam-golang-example/...
cd $GOPATH/src/github.com/cpliakas/aws-sam-golang-example

Usage

Run the API Locally

⚠ Make sure to install all the Prerequisites. On Mac OSX and Windows, ensure that the Docker VM is running.

GOARCH=amd64 GOOS=linux go build -o api ./service/api
sam local start-api

or ...

make run

You can now consume the API using your tool of choice. HTTPie is pretty awesome.

http localhost:3000/

HTTP/1.1 200 OK
Content-Length: 28
Content-Type: application/json; charset=utf8
Date: Sat, 03 Feb 2018 20:12:07 GMT

{
    "message": "Hello, world!"
}

Run the Worker Locally

TODO

Deploy to AWS

First, set the following environment variables replacing <MY-BUCKET-NAME> and <MY-STACK-NAME> as appropriate:

export S3_BUCKET="<MY-BUCKET-NAME>"
export STACK_NAME="<MY-STACK-NAME>"

Now build, package, and deploy the application:

GOOS=linux GOARCH=amd64 go build -o api ./service/api
GOOS=linux GOARCH=amd64 go build -o error ./service/error
GOOS=linux GOARCH=amd64 go build -o worker ./service/worker

sam package --template-file template.yaml --s3-bucket $S3_BUCKET --output-template-file packaged.yaml
sam deploy --stack-name $STACK_NAME --template-file packaged.yaml --capabilities CAPABILITY_IAM

or ...

make deploy

Consume the Endpoint

The API endpoint is captured in the CloudFormation stack's Endpoint output key. Either view the output value via the AWS Management Console, or run the following command assuming the jq tool is installed:

aws cloudformation describe-stacks --stack-name $STACK_NAME | jq -r '.Stacks[0].Outputs[0].OutputValue'

Again, HTTPie is a pretty awesome tool.

View AWS Logs

Run the following command to get the CloudWatch logs for the API.

sam logs -n Api --stack-name $STACK_NAME

Replace Api with Worker or Error to get logs for the Lambda functions in those resources as well.

⚠ The sam tool will throw a nasty stack trace if you try to view the logs before the Lambda function has been invoked. Only run this command after you have made requests to the corresponding handlers.