REST API microservice in Go

Why this?

Offered Features

API Features

1. OWASP Compliant Open API 3 Specification: Refer to OpenApi-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. Standardized Error Handling: Consistent error response format across all endpoints
5. API Versioning: URL-based versioning with backward compatibility
6. Internal vs External APIs: Separate authentication and access controls
7. Model Separation: Clear distinction between internal and external data representations

Go Application Features

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

Tooling

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.

Folder Structure

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

Control Flow

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 }

Loading

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.

Get Started

git clone https://github.com/rameshsunkara/go-rest-api-example.git
cd go-rest-api-example
make start

Your API is now running at http://localhost:8080

Try it out:

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

QuickStart

Pre-requisites

• Docker
• Docker Compose
• Make
• golangci-lint
• docker-buildx

Frequently used commands

start                          Start all necessary services and API server
run                            Run the API server
setup                          Start only dependencies
test                           Run tests with coverage

Development commands

lint                           Run the linter
lint-fix                       Run the linter and fix issues
clean                          Clean all Docker resources (keeps database data)
clean-all                      Clean all Docker resources including volumes (removes database data)
clean-volumes                  Remove only the docker-compose volumes (database data)
coverage                       Generate and display the code coverage report
go-work                        Generate Go work file
owasp-report                   Generate OWASP report
tidy                           Tidy Go modules

CI commands

build                          Build the API server binary
ci-coverage                    Check if test coverage meets the threshold
format                         Format Go code
version                        Display the current version of the API server

Docker commands

docker-build                   Build the Docker image
docker-build-debug             Build the Docker image without cache
docker-clean                   Clean all Docker resources
docker-clean-build-images      Remove build images
docker-compose-up              Start docker-compose services
docker-compose-down            Stop docker-compose services
docker-compose-down-volumes    Stop docker-compose services and remove volumes
docker-remove                  Remove Docker images and containers
docker-run                     Run the Docker container
docker-start                   Build and run the Docker container
docker-stop                    Stop the Docker container

Tools

1. Routing - Gin
2. Logging - zerolog
3. Database - MongoDB
4. Container - Docker

TODO

• Add comprehensive API documentation with examples
• Implement database migration system
• Add distributed tracing (OpenTelemetry integration)
• Implement circuit breaker pattern for external dependencies
• Add metrics collection and Prometheus integration
• Implement rate limiting middleware
• Add comprehensive integration tests
• Add git hooks for pre-commit and pre-push
• Implement all remaining OWASP security checks
• Add Kubernetes deployment manifests

Good to have

• Enhanced Data Models: Add validation, relationships, and business logic
• Cloud Deployment: Kubernetes manifests and Helm charts
• Advanced Monitoring: APM integration, alerting, and dashboards
• Caching Layer: Redis integration for performance optimization
• Event Sourcing: Event-driven architecture with message queues
• Multi-database Support: PostgreSQL, CockroachDB adapters
• Advanced Security: JWT tokens, OAuth2, RBAC implementation
• Performance Testing: Load testing scenarios and benchmarks
• Documentation: Auto-generated API docs and architectural decision records

References

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

Contribute

• Please feel free to Open PRs
• Please create issues with any problem you noticed
• Please suggest any improvements

Why this?

I embarked on the endeavor of crafting my own open-source boilerplate repository for several reasons:

After years of developing Full Stack applications using ReactJS and JVM-based languages, I observed that existing boilerplates tended to be either excessive or insufficient for my needs. Consequently, I resolved to construct my own, while adhering rigorously to the principles and guidelines of Go. While similarities with popular Go boilerplate templates may be evident, I have customized this repository to better align with my preferences and accumulated experiences. (My apologies if I inadvertently overlooked crediting any existing templates.)

I yearned for the autonomy to meticulously select the tools for fundamental functionalities such as Routing, Logging, and Configuration Management, ensuring seamless alignment with my personal preferences and specific requirements.

What this is not?

• This isn't a complete solution for all your needs. It's more like a basic template to kickstart your project.
• This isn't the best place to begin if you want to make an online store. What I've provided is just a simple tool for managing data through an API.