{"id":16735758,"url":"https://github.com/mrz1836/go-api-gateway","last_synced_at":"2026-05-16T22:03:14.369Z","repository":{"id":168222222,"uuid":"604287314","full_name":"mrz1836/go-api-gateway","owner":"mrz1836","description":"✴️ Example using AWS API Gateway, Lambda and Go","archived":false,"fork":false,"pushed_at":"2025-06-09T10:53:38.000Z","size":755,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-09T11:45:35.664Z","etag":null,"topics":["api-gateway","aws","aws-sam","cloudformation","golang","lambda","serverless"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrz1836.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"mrz1836","custom":"https://mrz1818.com/?tab=tips\u0026utm_source=github\u0026utm_medium=sponsor-link\u0026utm_campaign=go-template\u0026utm_term=go-template\u0026utm_content=go-template"}},"created_at":"2023-02-20T18:27:24.000Z","updated_at":"2025-06-09T10:53:36.000Z","dependencies_parsed_at":"2023-12-25T11:31:44.333Z","dependency_job_id":"dd94670a-bc1a-4d26-8b41-be25e13c962d","html_url":"https://github.com/mrz1836/go-api-gateway","commit_stats":null,"previous_names":["mrz1836/go-api-gateway"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/mrz1836/go-api-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-api-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-api-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-api-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-api-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrz1836","download_url":"https://codeload.github.com/mrz1836/go-api-gateway/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-api-gateway/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266596689,"owners_count":23953891,"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","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["api-gateway","aws","aws-sam","cloudformation","golang","lambda","serverless"],"created_at":"2024-10-13T00:07:10.253Z","updated_at":"2026-05-16T22:03:09.347Z","avatar_url":"https://github.com/mrz1836.png","language":"Makefile","funding_links":["https://github.com/sponsors/mrz1836","https://mrz1818.com/?tab=tips\u0026utm_source=github\u0026utm_medium=sponsor-link\u0026utm_campaign=go-template\u0026utm_term=go-template\u0026utm_content=go-template"],"categories":[],"sub_categories":[],"readme":"# API Gateway -\u003e Lambda (Go)\n\u003e Example using multiple Go functions using the same common library - with integrated CI/CD\n\u003e\n[![Build Status](https://img.shields.io/github/actions/workflow/status/mrz1836/go-api-gateway/run-tests.yml?branch=master\u0026logo=github\u0026v=2)](https://github.com/mrz1836/go-api-gateway/actions)\n[![Release](https://img.shields.io/github/release/mrz1836/go-api-gateway.svg?logo=github\u0026style=flat\u0026v=2)](https://github.com/mrz1836/go-api-gateway/releases)\n[![Go](https://img.shields.io/badge/Go-1.23.xx-blue.svg?v=2)](https://golang.org/)\n[![codecov](https://codecov.io/gh/mrz1836/go-api-gateway/branch/master/graph/badge.svg?token=C2ZRLM49RV\u0026v=2)](https://codecov.io/gh/mrz1836/go-api-gateway)\n[![Sponsor](https://img.shields.io/badge/sponsor-mrz1836-181717.svg?logo=github\u0026style=flat\u0026v=2)](https://github.com/sponsors/mrz1836)\n[![Donate](https://img.shields.io/badge/donate-bitcoin-ff9900.svg?logo=bitcoin\u0026style=flat\u0026v=2)](https://mrz1818.com/?tab=tips\u0026utm_source=github\u0026utm_medium=sponsor-link\u0026utm_campaign=go-api-gateway\u0026utm_term=go-api-gateway\u0026utm_content=go-api-gateway)\n\n\u003cbr/\u003e\n\n## Table of Contents\n- [Installation](#installation)\n- [Deployment \u0026 Hosting](#deployment--hosting)\n- [Documentation](#documentation)\n- [Examples \u0026 Tests](#examples--tests)\n- [Code Standards](#code-standards)\n- [Maintainers](#maintainers)\n- [Contributing](#contributing)\n- [License](#license)\n\n\u003cbr/\u003e\n\n## Installation\n\n#### Prerequisites\n- [An AWS account](https://aws.amazon.com/) \n    - _Running functions locally_ requires permission to: [CodePipeline](https://aws.amazon.com/kms/) and [KMS](https://aws.amazon.com/kms/)\n    - _Deploying_ requires permission to: [KMS](https://aws.amazon.com/kms/), [SSM](https://aws.amazon.com/systems-manager/features/), [Secrets Manager](https://aws.amazon.com/secrets-manager/) and [Cloud Formation](https://aws.amazon.com/cloudformation/)\n- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) _(`brew install awscli`)_\n- [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install-mac.html) _(`brew tap aws/tap \u0026\u0026 brew install aws-sam-cli`)_\n    - Running functions locally requires: [Docker](https://docs.docker.com/install)\n- [Golang](https://golang.org/doc/install) _(`brew install go`)_\n- [Docker](https://docker.com/) Used for running the local version of the API and functions\n- [DockerHub](https://hub.docker.com/) Used for custom Go images in CodeBuild\n\nClone or [go get](https://golang.org/doc/articles/go_command.html) the files locally\n```shell script\ngo get github.com/mrz1836/go-api-gateway\ncd $GOPATH/src/github.com/mrz1836/go-api-gateway\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eSetup to run locally\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\n**1)** Start docker on your computer\n\n**2)** Build and start running! (runs on 127.0.0.1:3000)\n```shell script\nmake build;\nmake start;\n``` \n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## Deployment \u0026 Hosting\nThis repository has CI integration using [AWS CodePipeline](https://aws.amazon.com/codepipeline/).\n\nDeploying to the `master` branch will automatically start the process of shipping the code to [AWS Lambda](https://aws.amazon.com/lambda/).\n\nAny changes to the environment via the [AWS CloudFormation template](application.yaml) will be applied.\nThe actual build process can be found in the [buildspec.yml](buildspec.yml) file.\n\nThe application relies on [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)\nand [AWS SSM](https://aws.amazon.com/systems-manager/features/) to store environment variables.\nSensitive environment variables are encrypted using [AWS KMS](https://aws.amazon.com/kms/) and then decrypted at runtime.\n\nDeploy different environments by changing the `\u003cstage\u003e` to `production` or `staging` as an example.\nThe default stage is `production` if not specified.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eCreate Environment Encryption Key(s) (AWS)\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nCreate a `KMS Key` per `\u003cstage\u003e` for your application(s) to encrypt environment variables\n```shell script\nmake create-env-key stage=\"\u003cstage\u003e\";\n```\n\nThis will also store the `kms_key_id` in [SSM](https://aws.amazon.com/systems-manager/features/) located at: `/\u003capplication\u003e/\u003cstage\u003e/kms_key_id` \n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eManage DockerHub Credentials (AWS)\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\n- `username` is your DockerHub username\n- `password` is either your DockerHub password or auth_token (use auth_token if your account has 2FA)\n- `kms_key_id` is from the previous step _(Create Environment Encryption Keys)_\n\nAdd or update your application DockerHub credentials\n```shell script\nmake save-dockerhub-credentials \\\n      username=\"YOUR_DOCKERHUB_USERNAME\" \\\n      password=\"YOUR_DOCKERHUB_PASSWORD\" \\\n      kms_key_id=\"YOUR_KMS_KEY_ID\" \\\n      stage=\"\u003cstage\u003e\";\n```\n\nNext run:\n```shell\nmake save-dockerhub-arn \\\n      arn=\"YOUR_SECRETS_ARN\" \\\n      stage=\"\u003cstage\u003e\";\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eManage Environment Secrets (AWS)\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\n- `github_token` is a GitHub Personal Token for webhooks\n- `example_secret` is an example secret value that will be encrypted\n- `kms_key_id` is from the previous step (Create Environment Encryption Keys)\n\nAdd or update your GitHub personal access token\n```shell script\nmake save-secrets \\\n      github_token=\"YOUR_GITHUB_TOKEN\" \\\n      example_secret=\"YOUR_EXAMPLE_SECRET_VALUE\" \\\n      kms_key_id=\"YOUR_KMS_KEY_ID\" \\\n      stage=\"\u003cstage\u003e\";\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eCreate New CI \u0026 Hosting Environment (AWS)\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\n\u003cimg src=\".github/IMAGES/infrastructure-diagram.png\" alt=\"infrastructure diagram\" height=\"400\" /\u003e\n\nThis will create a new [AWS CloudFormation](https://aws.amazon.com/cloudformation/) stack with:\n- (1) [API Gateway](https://aws.amazon.com/api-gateway/) RESTful API interface\n- (1) [Lambda](https://aws.amazon.com/lambda/) Function(s) (Golang Runtime)\n- (1) [CloudWatch LogGroup](https://aws.amazon.com/cloudwatch/) for the Lambda function output\n- (1) [CodePipeline](https://aws.amazon.com/codepipeline/) with multiple stages to deploy the application from GitHub\n- (1) [CodePipeline Webhook](https://aws.amazon.com/codepipeline/) to receive GitHub notifications from a specific `branch:name`\n- (1) [CodeBuild Project](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html) to test, build and deploy the app\n- (2) [Service Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) for working with CodeBuild and CodePipeline\n\n**NOTE:** Requires an existing S3 bucket for artifacts and sam-cli deployments (located in the [Makefile](Makefile))\n\nOne command will build, test, package and deploy the application to AWS using the default `production` stage and using default tags. \nAfter initial deployment, updating the function is as simple as committing to GitHub.\n```shell script\nmake deploy;\n```\n\n_(Example)_ Customized deployment for another stage\n```shell script\nmake deploy stage=\"development\" branch=\"development\";\n``` \n\n_(Example)_ Customized deployment for a feature branch\n```shell script\nmake deploy stage=\"development\" branch=\"some-feature\" feature=\"some-feature\";\n```\n\n_(Example)_ Customized S3 bucket location\n```shell script\nmake deploy bucket=\"some-S3-bucket-location\";\n```\n\n_(Example)_ Customized tags for the deployment\n```shell script\nmake deploy tags=\"MyTag=some-value AnotherTag=some-value\";\n```  \n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eTear Down CI \u0026 Hosting Environment (AWS)\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nRemove the stack (using default stage: `production`)\n```shell script\nmake teardown;\n```   \n\n_(Example)_ Teardown another stack via stage\n```shell script\nmake teardown stage=\"development\";\n``` \n\n_(Example)_ Teardown a feature/branch stack\n```shell script\nmake teardown stage=\"development\" feature=\"some-feature\";\n``` \n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eLambda Logging\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nView all the logs in [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:log-groups) via Log Groups\n```text\n/aws/lambda/\u003capp_name\u003e-\u003cstage_name\u003e\n```\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## Documentation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eRelease Deployment\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\n[goreleaser](https://github.com/goreleaser/goreleaser) for easy binary or library deployment to GitHub and can be installed via: `brew install goreleaser`.\n\nThe [.goreleaser.yml](.goreleaser.yml) file is used to configure [goreleaser](https://github.com/goreleaser/goreleaser).\n\nUse `make release-snap` to create a snapshot version of the release, and finally `make release` to ship to production.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eMakefile Commands\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nView all `makefile` commands\n```shell script\nmake help\n```\n\nList of all current commands:\n```text\naws-param-certificate           Returns the ssm location for the domain ssl certificate id\naws-param-dockerhub             Returns the ssm location for the DockerHub ARN\naws-param-zone                  Returns the ssm location for the host zone id\nbuild                           Build the SAM application\nclean                           Remove previous builds, test cache, and packaged releases\nclean-mods                      Remove all the Go mod cache\ncoverage                        Shows the test coverage\ncreate-env-key                  Creates a new key in KMS for a new stage\ncreate-secret                   Creates an secret into AWS SecretsManager\ndecrypt                         Decrypts data using a KMY Key ID (awscli v2)\ndecrypt-deprecated              Decrypts data using a KMY Key ID (awscli v1)\ndeploy                          Build, prepare and deploy\ndiff                            Show the git diff\nencrypt                         Encrypts data using a KMY Key ID (awscli v2)\nenv-key-location                Returns the environment encryption key location\ngenerate                        Runs the go generate command in the base of the repo\ngodocs                          Sync the latest tag with GoDocs\nhelp                            Show this help message\ninstall                         Install the application\ninstall-go                      Install the application (Using Native Go)\ninstall-releaser                Install the GoReleaser application\ninvalidate-cache                Invalidates a cloudfront cache based on path\nlint                            Run the golangci-lint application (install if not found)\npackage                         Process the CF template and prepare for deployment\nrelease                         Full production release (creates release in Github)\nrelease-snap                    Test the full release (build binaries)\nrelease-test                    Full production test release (everything except deploy)\nreplace-version                 Replaces the version in HTML/JS (pre-deploy)\nsave-dockerhub-arn              Updates the ARN for the DockerHub secret\nsave-dockerhub-credentials      Helper for saving DockerHub credentials to Secrets Manager\nsave-domain-info                Saves the zone id and the ssl id for use by CloudFormation\nsave-param                      Saves a plain-text string parameter in SSM\nsave-param-encrypted            Saves an encrypted string value as a parameter in SSM\nsave-secrets                    Helper for saving application secrets to Secrets Manager (extendable for more secrets)\nstart                           Start the application\ntag                             Generate a new tag and push (tag version=0.0.0)\ntag-remove                      Remove a tag if found (tag-remove version=0.0.0)\ntag-update                      Update an existing tag to current commit (tag-update version=0.0.0)\nteardown                        Deletes the entire stack\ntest                            Runs lint and ALL tests\ntest-ci                         Runs all tests via CI (exports coverage)\ntest-ci-no-race                 Runs all tests via CI (no race) (exports coverage)\ntest-ci-short                   Runs unit tests via CI (exports coverage)\ntest-no-lint                    Runs just tests\ntest-short                      Runs vet, lint and tests (excludes integration tests)\ntest-unit                       Runs tests and outputs coverage\nuninstall                       Uninstall the application (and remove files)\nupdate-linter                   Update the golangci-lint package (macOS only)\nupdate-secret                   Updates an existing secret in AWS SecretsManager\nupload-files                    Upload/puts files into S3 bucket\nvet                             Run the Go vet application\n```\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## Examples \u0026 Tests\nAll unit tests run via [GitHub Actions](https://github.com/mrz1836/go-api-gateway/actions) and\nuse [Go version 1.23.x](https://golang.org/doc/go1.23). View the [configuration file](.github/workflows/run-tests.yml).\n\nRun all tests (including integration tests)\n```shell script\nmake test\n```\n\nRun unit tests (excluding integration tests)\n```shell script\nmake test-short\n```\n\n\u003cbr/\u003e\n\n## Code Standards\nRead more about this Go project's [code standards](.github/CODE_STANDARDS.md).\n\n\u003cbr/\u003e\n\n## Maintainers\n\n| [\u003cimg src=\"https://github.com/mrz1836.png\" height=\"50\" alt=\"MrZ\" /\u003e](https://github.com/mrz1836) |\n|:------------------------------------------------------------------------------------------------:|\n|                                [MrZ](https://github.com/mrz1836)                                 |\n\n\u003cbr/\u003e\n\n## Contributing\nView the [contributing guidelines](.github/CONTRIBUTING.md) and please follow the [code of conduct](.github/CODE_OF_CONDUCT.md).\n\n### How can I help?\nAll kinds of contributions are welcome :raised_hands:!\nThe most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon:.\nYou can also support this project by [becoming a sponsor on GitHub](https://github.com/sponsors/mrz1836) :clap:\nor by making a [**bitcoin donation**](https://mrz1818.com/?tab=tips\u0026utm_source=github\u0026utm_medium=sponsor-link\u0026utm_campaign=go-api-gateway\u0026utm_term=go-api-gateway\u0026utm_content=go-api-gateway) to ensure this journey continues indefinitely! :rocket:\n\n[![Stars](https://img.shields.io/github/stars/mrz1836/go-api-gateway?label=Please%20like%20us\u0026style=social\u0026v=1)](https://github.com/mrz1836/go-api-gateway/stargazers)\n\n## License\n\n[![License](https://img.shields.io/github/license/mrz1836/go-api-gateway.svg?style=flat\u0026v=1)](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrz1836%2Fgo-api-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrz1836%2Fgo-api-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrz1836%2Fgo-api-gateway/lists"}