{"id":30305723,"url":"https://github.com/nicobistolfi/go-lambda-api","last_synced_at":"2025-10-09T07:14:47.719Z","repository":{"id":307379677,"uuid":"1029352774","full_name":"nicobistolfi/go-lambda-api","owner":"nicobistolfi","description":"A minimal Golang HTTP API built with the standard library, featuring API key authentication and designed for serverless deployment on AWS Lambda.","archived":false,"fork":false,"pushed_at":"2025-07-30T23:20:13.000Z","size":20,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-17T08:52:04.766Z","etag":null,"topics":["aws-lambda","go","go-net-http","golang","lambda","net-http","serverless","serverless-framework"],"latest_commit_sha":null,"homepage":"","language":"Go","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/nicobistolfi.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,"zenodo":null}},"created_at":"2025-07-30T23:19:07.000Z","updated_at":"2025-08-01T02:29:52.000Z","dependencies_parsed_at":"2025-07-31T01:06:50.944Z","dependency_job_id":null,"html_url":"https://github.com/nicobistolfi/go-lambda-api","commit_stats":null,"previous_names":["nicobistolfi/go-lambda-api"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/nicobistolfi/go-lambda-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicobistolfi%2Fgo-lambda-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicobistolfi%2Fgo-lambda-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicobistolfi%2Fgo-lambda-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicobistolfi%2Fgo-lambda-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicobistolfi","download_url":"https://codeload.github.com/nicobistolfi/go-lambda-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicobistolfi%2Fgo-lambda-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000991,"owners_count":26082972,"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-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":["aws-lambda","go","go-net-http","golang","lambda","net-http","serverless","serverless-framework"],"created_at":"2025-08-17T08:37:28.780Z","updated_at":"2025-10-09T07:14:47.714Z","avatar_url":"https://github.com/nicobistolfi.png","language":"Go","readme":"# Go Lambda API\n\nA minimal Golang HTTP API built with the standard library, featuring API key authentication and designed for serverless deployment on AWS Lambda.\n\n## Features\n\n- ✅ Pure Go implementation using only `net/http` (no external frameworks)\n- ✅ API key authentication via `X-API-Key` header\n- ✅ Health check endpoint at `/health`\n- ✅ Graceful shutdown support\n- ✅ Request logging middleware\n- ✅ Comprehensive unit tests\n- ✅ AWS Lambda deployment ready with Serverless Framework\n- ✅ Dual deployment: Run locally as HTTP server or deploy to AWS Lambda\n\n## Project Structure\n\n```\n/\n├── cmd/\n│   ├── api/\n│   │   └── main.go           # Local server entry point\n│   └── lambda/\n│       └── main.go           # AWS Lambda entry point\n├── internal/\n│   ├── handlers/\n│   │   ├── health.go         # Health check handler\n│   │   └── handlers_test.go  # Handler tests\n│   ├── middleware/\n│   │   ├── auth.go           # Authentication middleware\n│   │   └── auth_test.go      # Middleware tests\n│   └── server/\n│       ├── server.go         # Server setup and configuration\n│       └── server_test.go    # Server tests\n├── serverless.yml            # Serverless Framework configuration\n├── Taskfile.yml              # Task runner configuration\n├── .air.toml                 # Hot reload configuration\n├── Dockerfile                # Docker configuration\n├── .gitignore                # Git ignore file\n├── go.mod                    # Go module file\n└── README.md                 # This file\n```\n\n## Local Development Setup\n\n### Prerequisites\n\n- Go 1.21 or higher\n- Git\n- [Task](https://taskfile.dev) - Task runner (recommended)\n- (Optional) Serverless Framework for deployment\n- (Optional) AWS CLI configured with appropriate credentials\n- (Optional) Docker for containerized deployment\n\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/nicobistolfi/go-lambda-api.git\ncd go-lambda-api\n```\n\n2. Install dependencies:\n```bash\ngo mod download\n# or using Task\ntask mod\n```\n\n3. Create a `.env` file from the example:\n```bash\ncp .env.example .env\n# Edit .env and set your API_KEY\n```\n\n4. Install Task runner (if not already installed):\n```bash\n# macOS\nbrew install go-task/tap/go-task\n\n# Linux\nsh -c \"$(curl --location https://taskfile.dev/install.sh)\" -- -d\n\n# Windows (using Scoop)\nscoop install task\n```\n\n## Quick Start with Task\n\nView all available tasks:\n```bash\ntask --list\n# or simply\ntask\n```\n\nCommon operations:\n```bash\n# Run the server locally\ntask run\n\n# Run tests\ntask test\n\n# Run tests with coverage\ntask test-coverage\n\n# Build the binary\ntask build\n\n# Format code\ntask fmt\n\n# Start development server with hot reload\ntask dev\n```\n\n## Environment Variables Configuration\n\nThe application uses the following environment variables:\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `API_KEY` | API key for authentication | - | Yes |\n| `PORT` | Port to run the server on | `8080` | No |\n\n## Running the Server Locally\n\n### Using Task (Recommended)\n\n```bash\n# Run with default dev API key\ntask run\n\n# Run with custom API key\nAPI_KEY=\"your-secret-api-key\" task run\n\n# Run on custom port\nPORT=3000 task run\n```\n\n### Using Go directly\n\n1. Set the required environment variables:\n```bash\nexport API_KEY=\"your-secret-api-key\"\nexport PORT=\"8080\"  # Optional, defaults to 8080\n```\n\n2. Run the server:\n```bash\ngo run cmd/api/main.go\n```\n\n### Using Docker\n\n```bash\n# Build and run in Docker\nAPI_KEY=\"your-secret-api-key\" task docker\n```\n\nThe server will start on `http://localhost:8080` (or the port specified).\n\n### Testing the API\n\nHealth check (no authentication required):\n```bash\ncurl http://localhost:8080/health\n# or using Task\ncurl http://localhost:8080/health | jq .\n```\n\nExpected response:\n```json\n{\"status\":\"ok\"}\n```\n\nWith authentication (for future authenticated endpoints):\n```bash\ncurl -H \"X-API-Key: your-secret-api-key\" http://localhost:8080/some-endpoint\n# or using Task with custom API key\nAPI_KEY=\"your-secret-api-key\" task run\n```\n\n## Running Tests\n\n### Using Task (Recommended)\n\n```bash\n# Run all tests\ntask test\n\n# Run tests with coverage\ntask test-coverage\n\n# Run linter\ntask lint\n\n# Clean build artifacts\ntask clean\n```\n\n### Using Go directly\n\nRun all tests with coverage:\n```bash\ngo test -v -cover ./...\n```\n\nRun tests for a specific package:\n```bash\ngo test -v ./internal/handlers\ngo test -v ./internal/middleware\ngo test -v ./internal/server\n```\n\nGenerate coverage report:\n```bash\ngo test -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out -o coverage.html\n```\n\n## Serverless Deployment\n\n### Prerequisites\n\n1. Install Serverless Framework:\n```bash\nnpm install -g serverless\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Configure AWS credentials:\n```bash\naws configure\n```\n\n### Deployment Steps\n\n#### Using Task (Recommended)\n\nMake sure you have a `.env` file with your API_KEY set, or pass it explicitly:\n\n```bash\n# Deploy using .env file\ntask deploy\n\n# Or deploy with explicit API_KEY\nAPI_KEY=\"your-api-key\" task deploy\n\n# Deploy to specific stage\nSTAGE=production task deploy\n\n# View logs\ntask logs\n```\n\n#### Using Serverless directly\n\n1. Set your API key as an environment variable:\n```bash\nexport API_KEY=\"your-production-api-key\"\n```\n\n2. Deploy to AWS:\n```bash\nserverless deploy --stage production --region us-west-1\n```\n\n3. Deploy to a specific stage:\n```bash\nserverless deploy --stage dev\nserverless deploy --stage staging\nserverless deploy --stage production\n```\n\n### Viewing Logs\n\nView function logs:\n```bash\nserverless logs -f api --tail\n# or using Task\ntask logs\n```\n\n### Removing the Deployment\n\nRemove the deployed service:\n```bash\nserverless remove --stage production\n# or using Task\nSTAGE=production serverless remove\n```\n\n## API Documentation\n\n### Endpoints\n\n#### `GET /health`\nHealth check endpoint that returns the service status.\n\n**Authentication**: Not required\n\n**Response:**\n- Status: `200 OK`\n- Body: `{\"status\": \"ok\"}`\n\n### Authentication\n\nAll endpoints (except `/health`) require API key authentication via the `X-API-Key` header.\n\n**Example:**\n```bash\ncurl -H \"X-API-Key: your-api-key\" https://your-api-url.com/endpoint\n```\n\n**Error Responses:**\n- `401 Unauthorized` - Missing or invalid API key\n  - `{\"error\": \"Missing API key\"}`\n  - `{\"error\": \"Invalid API key\"}`\n  - `{\"error\": \"API key not configured\"}`\n\n## Development Guidelines\n\n### Development Tools\n\nInstall development dependencies:\n```bash\ngo install github.com/cosmtrek/air@latest\ngo install github.com/golangci/golangci-lint/cmd/golangci-lint@latest\n```\n\nThis installs:\n- `air` - Hot reload for development\n- `golangci-lint` - Linting tool\n\nStart development server with hot reload:\n```bash\ntask dev\n```\n\nRun code checks:\n```bash\n# Format code\ntask fmt\n\n# Run linter (if installed)\ntask lint\n\n# Run default task (format, test, build)\ntask default\n```\n\nClean build artifacts:\n```bash\ntask clean\n```\n\n### Adding New Endpoints\n\n1. Create a new handler in `internal/handlers/`\n2. Add authentication by wrapping with `middleware.AuthMiddleware()`\n3. Register the route in `internal/server/server.go`\n4. Write comprehensive tests\n\nExample:\n```go\n// In internal/server/server.go\nmux.HandleFunc(\"/api/users\", middleware.AuthMiddleware(handlers.UsersHandler))\n```\n\n### Code Style\n\n- Follow standard Go conventions\n- Use `gofmt` for formatting\n- Keep functions small and focused\n- Write tests for all new functionality\n- Use meaningful variable and function names\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Server fails to start**\n   - Check if the port is already in use\n   - Ensure all environment variables are set correctly\n\n2. **Authentication failures**\n   - Verify the `API_KEY` environment variable is set\n   - Check that the `X-API-Key` header matches exactly\n\n3. **Deployment issues**\n   - Ensure AWS credentials are configured\n   - Check Serverless Framework version compatibility\n   - Verify the Go version matches the Lambda runtime\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicobistolfi%2Fgo-lambda-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicobistolfi%2Fgo-lambda-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicobistolfi%2Fgo-lambda-api/lists"}