This project illustrates how to build an API in Amazon Web Services (AWS) using Go.
The main goal of this project is to illustrate how to build a maintainable real world REST API hosted in AWS using Go. To enable this I have added examples of:
- Contract first OpenAPI using code generation
- Support running in Lambda with Amazon API Gateway with validation of inputs
- Logging with meta data including lambda request identifiers
- Provide an API Gateway client using sigv4 with Go.
- Protobuf based versioned storage using DynamoDB
- Local testing with docker using github.com/ory/dockertest/v3 and DynamoDB Local
- CLI using github.com/alecthomas/kong with logging and sub commands
- Linting using golangci-lint
The CLI provides a simple interface to access data via the API.
$ customer-cli --help
Usage: customer-cli --url=STRING <command>
Flags:
-h, --help Show context-sensitive help.
--version
--debug
--url=STRING
Commands:
create-customer --url=STRING --name=STRING --labels=LABELS,...
New Customer.
get-customer --url=STRING --id=STRING
Read Customer.
list-customers --url=STRING
Read a list of Customers.
Run "customer-cli <command> --help" for more information on a command.
Reading a list of customers from the API.
$ customer-cli --url=https://xxxxxxxxxx.execute-api.us-west-2.amazonaws.com/Prod list-customers | jq .
6:33PM INF cmd/customer-cli/commands/list_customers.go:18 > get a list of customers from the api
6:33PM INF cmd/customer-cli/apigw/apigw.go:25 > signing request host=xxxxxxxxxx.execute-api.us-west-2.amazonaws.com
{
"customers": [
{
"created_at": "2020-10-22T17:38:34.242777542Z",
"description": "test",
"id": "01EN8P84M2P9RQJ1XV3XQR4DZM",
"labels": [
"test"
],
"name": "test",
"updated_at": "2020-10-22T17:38:34.242778239Z"
},
{
"created_at": "2020-10-22T17:41:23.701550324Z",
"description": "test",
"id": "01EN8PDA3N91HNQEVV16HX6J27",
"labels": [
"test"
],
"name": "test2",
"updated_at": "2020-10-22T17:41:23.701551096Z"
},
{
"created_at": "2020-10-23T02:21:37.259975291Z",
"description": "test",
"id": "01EN9M5W3BDKGR3RGCEGNSBYHQ",
"labels": [
"test"
],
"name": "test3",
"updated_at": "2020-10-23T02:21:37.259975968Z"
}
]
}
In this example I use a few conventions when deploying the software, this is done to support multiple environments, and branch based deploys which are common when building and testing.
AppName
- Label given service(s) with some collective role in a system.Stage
- The stage where the application is running in, e.g., dev, prod.Branch
- The branch this release is deployed from, typically something other thanmain
ormaster
is only used when testing in parallel.
Create an .envrc
using the .envrc.example
and update it with your settings, this is used with direnv.
cp .envrc.example .envrc
Run make to deploy the stack.
make
To invoke a simple API which is authenticated using sigv4 I have included a generated client, to use this you will need AWS_REGION
and AWS_PROFILE
exported as environment variables.
go run cmd/customer-cli/main.go --url=https://xxxxxxxxxx.execute-api.us-west-2.amazonaws.com/Prod list-customers
- github.com/aws/aws-lambda-go
- github.com/apex/gateway
- github.com/rs/zerolog
- github.com/deepmap/oapi-codegen
- github.com/labstack/echo/v4
- github.com/wolfeidau/dynastore
To enable fast iteration on changes I have included a local development server version of the API, this runs in docker-compose and uses a bit of mock data, along with DynamoDB Local and file change watching to provide a realtime development experience.
To use this feature run.
make docker-compose
Then load up the openapi in postman, or hit the service curl as follows.
curl -v http://localhost:3000/customers | jq .
Or using the CLI with --disable-signing
to avoid including sigv4 signatures.
go run cmd/customer-cli/main.go --url http://localhost:3000 --disable-signing list-customers | jq .
This application is released under Apache 2.0 license and is copyright Mark Wolfe.