Skip to content

This project illustrates how to build an API in AWS using Go.

License

Notifications You must be signed in to change notification settings

wolfeidau/realworld-aws-api

Repository files navigation

realworld-aws-api

This project illustrates how to build an API in Amazon Web Services (AWS) using Go.

Goals

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:

CLI

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"
    }
  ]
}

Conventions

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 than main or master is only used when testing in parallel.

Deployment

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

Client

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

Libraries

Development

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 .

License

This application is released under Apache 2.0 license and is copyright Mark Wolfe.

About

This project illustrates how to build an API in AWS using Go.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published