{"id":20853763,"url":"https://github.com/wolfeidau/realworld-aws-api","last_synced_at":"2025-05-12T05:31:37.513Z","repository":{"id":39788025,"uuid":"305690231","full_name":"wolfeidau/realworld-aws-api","owner":"wolfeidau","description":"This project illustrates how to build an API in AWS using Go.","archived":false,"fork":false,"pushed_at":"2023-04-04T21:21:12.000Z","size":331,"stargazers_count":5,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-01T01:22:12.125Z","etag":null,"topics":["aws","go","lambda","openapi","rest"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wolfeidau.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-20T11:46:27.000Z","updated_at":"2024-01-20T01:26:26.000Z","dependencies_parsed_at":"2024-06-19T13:34:07.277Z","dependency_job_id":"0582a6e6-6fcf-4017-b9aa-a0b7c32c8631","html_url":"https://github.com/wolfeidau/realworld-aws-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfeidau%2Frealworld-aws-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfeidau%2Frealworld-aws-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfeidau%2Frealworld-aws-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfeidau%2Frealworld-aws-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wolfeidau","download_url":"https://codeload.github.com/wolfeidau/realworld-aws-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253682210,"owners_count":21946898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","go","lambda","openapi","rest"],"created_at":"2024-11-18T03:23:05.504Z","updated_at":"2025-05-12T05:31:34.934Z","avatar_url":"https://github.com/wolfeidau.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# realworld-aws-api\n\nThis project illustrates how to build an API in [Amazon Web Services (AWS)](https://aws.amazon.com/) using [Go](https://golang.org).\n\n# Goals\n\nThe 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:\n\n* Contract first [OpenAPI](https://swagger.io/specification/) using code generation\n* Support running in [Lambda](https://aws.amazon.com/lambda/) with [Amazon API Gateway](https://aws.amazon.com/api-gateway/) with validation of inputs\n* Logging with meta data including lambda request identifiers\n* Provide an [API Gateway](https://aws.amazon.com/api-gateway/) client using [sigv4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) with Go.\n* Protobuf based versioned storage using [DynamoDB](https://aws.amazon.com/dynamodb/)\n* Local testing with [docker](https://www.docker.com) using [github.com/ory/dockertest/v3](https://github.com/ory/dockertest) and [DynamoDB Local](https://hub.docker.com/r/amazon/dynamodb-local/)\n* CLI using [github.com/alecthomas/kong](https://github.com/alecthomas/kong) with logging and sub commands\n* Linting using [golangci-lint](https://github.com/golangci/golangci-lint)\n\n# CLI\n\nThe CLI provides a simple interface to access data via the API.\n\n```\n$ customer-cli --help\nUsage: customer-cli --url=STRING \u003ccommand\u003e\n\nFlags:\n  -h, --help          Show context-sensitive help.\n      --version\n      --debug\n      --url=STRING\n\nCommands:\n  create-customer --url=STRING --name=STRING --labels=LABELS,...\n    New Customer.\n\n  get-customer --url=STRING --id=STRING\n    Read Customer.\n\n  list-customers --url=STRING\n    Read a list of Customers.\n\nRun \"customer-cli \u003ccommand\u003e --help\" for more information on a command.\n\n```\n\nReading a list of customers from the API.\n\n```\n$ customer-cli --url=https://xxxxxxxxxx.execute-api.us-west-2.amazonaws.com/Prod list-customers  | jq .\n6:33PM INF cmd/customer-cli/commands/list_customers.go:18 \u003e get a list of customers from the api\n6:33PM INF cmd/customer-cli/apigw/apigw.go:25 \u003e signing request host=xxxxxxxxxx.execute-api.us-west-2.amazonaws.com\n{\n  \"customers\": [\n    {\n      \"created_at\": \"2020-10-22T17:38:34.242777542Z\",\n      \"description\": \"test\",\n      \"id\": \"01EN8P84M2P9RQJ1XV3XQR4DZM\",\n      \"labels\": [\n        \"test\"\n      ],\n      \"name\": \"test\",\n      \"updated_at\": \"2020-10-22T17:38:34.242778239Z\"\n    },\n    {\n      \"created_at\": \"2020-10-22T17:41:23.701550324Z\",\n      \"description\": \"test\",\n      \"id\": \"01EN8PDA3N91HNQEVV16HX6J27\",\n      \"labels\": [\n        \"test\"\n      ],\n      \"name\": \"test2\",\n      \"updated_at\": \"2020-10-22T17:41:23.701551096Z\"\n    },\n    {\n      \"created_at\": \"2020-10-23T02:21:37.259975291Z\",\n      \"description\": \"test\",\n      \"id\": \"01EN9M5W3BDKGR3RGCEGNSBYHQ\",\n      \"labels\": [\n        \"test\"\n      ],\n      \"name\": \"test3\",\n      \"updated_at\": \"2020-10-23T02:21:37.259975968Z\"\n    }\n  ]\n}\n```\n\n# Conventions\n\nIn 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.\n\n* `AppName` - Label given service(s) with some collective role in a system.\n* `Stage` - The stage where the application is running in, e.g., dev, prod.\n* `Branch` - The branch this release is deployed from, typically something other than `main` or `master` is only used when testing in parallel.\n\n# Deployment\n\nCreate an `.envrc` using the `.envrc.example` and update it with your settings, this is used with [direnv](https://direnv.net/).\n\n```\ncp .envrc.example .envrc\n```\n\nRun make to deploy the stack.\n\n```\nmake\n```\n\n# Client\n\nTo invoke a simple API which is authenticated using [sigv4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) I have included a generated client, to use this you will need `AWS_REGION` and `AWS_PROFILE` exported as environment variables.\n\n```\ngo run cmd/customer-cli/main.go --url=https://xxxxxxxxxx.execute-api.us-west-2.amazonaws.com/Prod list-customers\n```\n\n# Libraries\n\n* [github.com/aws/aws-lambda-go](https://github.com/aws/aws-lambda-go)\n* [github.com/apex/gateway](https://github.com/apex/gateway)\n* [github.com/rs/zerolog](https://github.com/rs/zerolog)\n* [github.com/deepmap/oapi-codegen](https://github.com/deepmap/oapi-codegen)\n* [github.com/labstack/echo/v4](https://github.com/labstack/echo/v4)\n* [github.com/wolfeidau/dynastore](https://github.com/wolfeidau/dynastore)\n\n# Development\n\nTo enable fast iteration on changes I have included a local development server version of the API, this runs in [docker-compose](https://docs.docker.com/compose/) and uses a bit of mock data, along with DynamoDB Local and file change watching to provide a realtime development experience.\n\nTo use this feature run.\n\n```\nmake docker-compose\n```\n\nThen load up the openapi in postman, or hit the service curl as follows.\n\n```\ncurl -v http://localhost:3000/customers | jq .\n```\n\nOr using the CLI with `--disable-signing` to avoid including sigv4 signatures.\n\n```\ngo run cmd/customer-cli/main.go --url http://localhost:3000 --disable-signing list-customers | jq .\n```\n\n# License\n\nThis application is released under Apache 2.0 license and is copyright [Mark Wolfe](https://www.wolfe.id.au).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfeidau%2Frealworld-aws-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolfeidau%2Frealworld-aws-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfeidau%2Frealworld-aws-api/lists"}