Repository files navigation

A production-ready REST API boilerplate built with Go, featuring MongoDB integration, comprehensive middleware, flight recorder tracing, and modern development practices.

• 🚀Production-Ready: Graceful shutdown, health checks, structured logging
• 🔒Security-First: OWASP compliant, multi-tier auth, security headers
• 📊Observability: Flight recorder tracing, Prometheus metrics, pprof profiling
• 🧪Test Coverage: 70%+ coverage threshold with parallel testing
• 🐳Docker-Ready: Multi-stage builds with BuildKit optimization
• 📝Well-Documented: OpenAPI 3 specification with Postman collection

# Clone and startgit clone https://github.com/rameshsunkara/go-rest-api-example.gitcd go-rest-api-examplemake start# Your API is now running at http://localhost:8080curl http://localhost:8080/healthz

• Features
• Architecture
• Getting Started
• Available Commands
• Tools & Stack
• Contributing

1. OWASP Compliant Open API 3 Specification: Refer toOpenApi-v1.yaml for details.
2. Production-Ready Health Checks:
   • /healthz endpoint with proper HTTP status codes (204/424)
   • Database connectivity validation
   • Dependency health monitoring
3. Comprehensive Middleware Stack:
   • Request Logging: Structured logging with request correlation
   • Authentication: Multi-tier auth (external/internal APIs)
   • Request ID Tracing: End-to-end request tracking
   • Panic Recovery: Graceful error handling and recovery
   • Security Headers: OWASP-compliant security header injection
   • Query Validation: Input validation and sanitization
   • Compression: Automatic response compression (gzip)
4. Flight Recorder Integration: Automatic trace capture for slow requests using Go 1.25's built-in flight recorder.
5. Standardized Error Handling: Consistent error response format across all endpoints
6. API Versioning: URL-based versioning with backward compatibility
7. Internal vs External APIs: Separate authentication and access controls
8. Model Separation: Clear distinction between internal and external data representations

1. Configuration Management: Environment-based configuration with validation
2. Graceful Shutdown: Proper signal handling with resource cleanup and connection draining
3. Production-Ready MongoDB Integration:
   • Connection pooling and health checks
   • Functional options pattern for flexible configuration
   • SRV and replica set support
   • Credential management via sidecar files
   • Query logging for debugging
4. Comprehensive Health Checks:/healthz endpoint with database connectivity validation
5. Structured Logging: Zero-allocation JSON logging with request tracing
6. Secrets Management: Secure credential loading from sidecar files
7. Effective Mocking: Interface-based design enabling comprehensive unit testing
8. Database Indexing: Automatic index creation for optimal query performance
9. Idiomatic Go Architecture: Clean separation of concerns with dependency injection
10. Parallel Testing: Race condition detection with atomic coverage reporting
11. Context-Aware Operations: Proper context propagation for cancellation and timeouts
12. Resource Management: Automatic cleanup of connections and resources

1. Dockerized Environment: Facilitates service deployment using DOCKER_BUILDKIT.
2. Makefile: Automates common tasks for developers.
3. GitHub Actions: Automates building, testing, code coverage reporting, and enforces the required test coverage threshold.
4. Multi-Stage Docker Build: Accelerates build processes.

go-rest-api-example/├── main.go├── internal/           # Private application code│   ├── config/         # Configuration management│   ├── db/             # Database repositories and data access│   ├── errors/         # Application error definitions│   ├── handlers/       # HTTP request handlers│   ├── middleware/     # HTTP middleware components│   ├── models/         # Domain models and data structures│   ├── server/         # HTTP server setup and lifecycle│   ├── utilities/      # Internal utilities│   └── mockData/       # Test and development data├── pkg/                # Public packages (can be imported)│   ├── logger/         # Structured logging utilities│   └── mongodb/        # MongoDB connection management├── localDevelopment/   # Local dev setup (DB init scripts, etc.)├── Makefile            # Development automation├── Dockerfile          # Container image definition├── docker-compose.yaml # Local development services├── OpenApi-v1.yaml     # API specification└── OpenApi-v1.postman_collection.json

flowchart LR   Request e1@==> Server   e1@{ animate: true }   Server e2@==> Router   e2@{ animate: true }   M@{ shape: processes, label: "Middlewares" }   Router e3@==> M   e3@{ animate: true }   C@{ shape: processes, label: "Handlers" }   M e4@==> C   e4@{ animate: true }   R@{ shape: processes, label: "Repos(DAO)" }   C e5@==> R   e5@{ animate: true }   id1[(Database)]   R e6@==> id1   e6@{ animate: true }

1. Request: Server receives the incoming request.
2. Server: Server processes the request and forwards it to the router.
3. Router: Router directs the request to the appropriate middleware(s).
4. Middlewares: The middlewares handle various tasks such as logging, authentication, security headers, tracing etc.,
5. Handlers: The request is passed to the appropriate handler, which validates the request and forwards it to the repository layer.
6. Repos(DAO): The repository layer communicates with the database to perform CRUD operations.

• Docker andDocker Compose
• Make

git clone https://github.com/rameshsunkara/go-rest-api-example.gitcd go-rest-api-examplemake start

Your API is now running athttp://localhost:8080

Try it out:

curl http://localhost:8080/api/v1/healthzcurl http://localhost:8080/api/v1/orders

start                          Start all necessary services and API serverrun                            Run the API server (requires dependencies running)setup                          Start only dependencies (MongoDB)test                           Run tests with coverage

lint                           Run the linterlint-fix                       Run the linter and fix issuestraceAnalyzeatracefile(usage: make trace TRACE_FILE=./traces/slow-request-GET-orders-1234567890.trace)clean                          Clean all Docker resources (keeps database data)clean-all                      Clean all Docker resources including volumes (removes database data)coverage                       Generate and display the code coverage report

build                          Build the API server binaryci-coverage                    Check if test coverage meets the thresholdformat                         Format Go codeversion                        Display the current version of the API server

docker-build                   Build the Docker imagedocker-start                   Build and run the Docker containerdocker-clean                   Clean all Docker resources

💡Tip: Runmake help to see all available commands.

• golangci-lint - For linting
• docker-buildx - For multi-platform builds

• gin-boilerplate
• go-rest-api
• go-base

Contributions are welcome! Here's how you can help:

• 🐛Found a bug?Open an issue
• 💡Have a feature idea?Start a discussion
• 🔧Want to contribute code? Fork the repo and submit a PR

After years of developing Full Stack applications using ReactJS and JVM-based languages, I found existing Go boilerplates were either too opinionated or too minimal. This project strikes a balance:

✅Just Right: Not too bloated, not too minimal✅Best Practices: Follows Go idioms and patterns✅Production-Tested: Battle-tested patterns from real-world applications✅Flexible: Easy to customize for your specific needs

❌ A complete e-commerce solution❌ A framework that does everything for you❌ The only way to structure a Go API

This is a solid foundation to build upon. Take what you need, leave what you don't.