golang-rest-api-template

🚀 Template Repository

This is a template repository for building REST APIs with Go. Click the "Use this template" button above to create your own repository based on this template.

Overview

This template includes everything you need to build a REST API with Go - logging, middleware, database setup, testing, and deployment configs.

Features

• Structured logging
• Middleware (auth, CORS, etc.)
• Config management
• API docs with Swagger
• Docker setup
• GitHub Actions CI/CD
• Automated releases with GoReleaser
• Database migrations
• Tests
• Makefile for common tasks

The main ones are:

• gorilla/mux for routing
• go-playground/validator for request validation
• go-sql-driver/mysql for MySQL database access
• jmoiron/sqlx for enhanced database access
• Masterminds/squirrel for SQL builder
• golang-migrate/migrate for database migrations
• swaggo/swag for API documentation generation
• strechr/testify for writing easier test assertions
• mockery for generating mock interfaces
• uber/zap for structured logging
• prometheus/client_golang for metrics
• otel for observability
• jaeger for distributed tracing
• Redis for cache

🎯 Quick Start (Using Template)

1. Create Repository from Template

Click the "Use this template" button at the top of this repository, or use GitHub CLI:

gh repo create my-go-api --template MitulShah1/golang-rest-api-template

2. Clone Your New Repository

git clone https://github.com/YOUR_USERNAME/my-go-api.git
cd my-go-api

3. Update Project Details

After creating your repository, update these files:

• go.mod - Update module name
• README.md - Update project name and description
• .github/workflows/go.yml - Update repository references if needed
• docker-compose.yml - Update service names if needed

4. Start Development

make help          # See all available commands
make env           # Create .env file
make docker_up     # Start with Docker
make test          # Run tests

Project Structure

golang-microservice-template/
│── cmd/
│   ├── server/                # Main entry point for the service
│   │   ├── main.go
│── config/
│   ├── config.go              # Application configuration
│── docs/                      # API documentation
│── internal/
│   ├── handlers/              # HTTP handlers
│   │   ├── server.go          # HTTP server
│   ├── services/              # Business logic
│   ├── repository/            # Data access layer
│── package/                   # Utility packages (database, logging, middleware, etc.)
│   ├── database/
│   │   ├── database.go
│── │   ├──migrations/         # Database migrations
│   ├── logger/
│   │   ├── logger.go
│   ├── middleware/
│   │   ├── basic_auth.go       # Basic authentication middleware
│   │   ├── cors.go             # CORS middleware
│   ├── ├── promotheus.go       # Prometheus metrics
│── test/
│   ├── e2e/                    # End-to-end tests
│── Dockerfile                  # Docker build configuration
│── docker-compose.yml          # Docker Compose setup
│── Makefile                    # Build automation
│── go.mod                      # Go module dependencies
│── go.sum                      # Dependencies lock file
│── README.md                   # Project documentation

Getting Started

Prerequisites

• Go 1.21+
• Docker and Docker Compose
• Make

All Make Commands

To Check All Commands:

make help

Running the Application

1; Clone the repository

git clone https://github.com/MitulShah1/golang-rest-api-template.git

2; Create .env file from .env.example add details

make env

3; Start the application using Docker Compose

make docker_up

Development

Build the application:

make build

Run tests:

make test

Generate API documentation:

make generate_docs

DB Migrations

Create Migration:

make create_migration

Run Migrations:

make migration_up

Down Migrations:

make migration_down

Configuration

Configuration is managed through .env. Environment variables can override these settings.

API Documentation

API documentation is generated using Swagger. The documentation is available at http://localhost:8080/swagger/index.html.

📊 Monitoring & Observability

The template includes a comprehensive monitoring stack with Grafana and Prometheus:

Monitoring Stack

• Prometheus: Time-series database for metrics collection
• Grafana: Visualization and dashboard platform
• Jaeger: Distributed tracing
• Application Metrics: Built-in Prometheus metrics middleware

Quick Start for Monitoring

1. Start the monitoring stack:

make docker_up

2. Access the monitoring tools:

• Grafana: http://localhost:3000 (admin/admin)
• Prometheus: http://localhost:9090
• Jaeger: http://localhost:16686
• Application Metrics: http://localhost:8080/metrics

Pre-configured Dashboards

The template includes a pre-configured Grafana dashboard with:

• Request rate and response time metrics
• Error rates by status code
• HTTP method distribution
• 95th percentile response times

For detailed monitoring setup instructions, see monitoring/README.md.

Prometheus Metrics

Prometheus metrics are exposed at http://localhost:8080/metrics.

Testing

• Unit tests are alongside the code
• Integration tests are in the test/ directory
• Run all tests with make test

Releases

This project uses GoReleaser for automated releases. Releases are triggered automatically when you push a version tag.

Creating a Release

1. Create and push a version tag:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

2. The GitHub Actions workflow will automatically:
   • Build binaries for multiple platforms (Linux, macOS, Windows)
   • Generate checksums
   • Create Docker images for AMD64 and ARM64
   • Publish to GitHub Container Registry
   • Create a GitHub release with changelog
   • Update pkg.go.dev documentation

Using Released Binaries

Download the latest release from the releases page:

# Linux AMD64
wget https://github.com/MitulShah1/golang-rest-api-template/releases/download/v1.0.0/golang-rest-api-template_1.0.0_Linux_x86_64.tar.gz
tar -xzf golang-rest-api-template_1.0.0_Linux_x86_64.tar.gz

# macOS ARM64
wget https://github.com/MitulShah1/golang-rest-api-template/releases/download/v1.0.0/golang-rest-api-template_1.0.0_Darwin_arm64.tar.gz
tar -xzf golang-rest-api-template_1.0.0_Darwin_arm64.tar.gz

Using Docker Images

Pull and run the Docker image:

# Pull the latest version
docker pull ghcr.io/mitulshah1/golang-rest-api-template:latest

# Or pull a specific version
docker pull ghcr.io/mitulshah1/golang-rest-api-template:v1.0.0

# Run the container
docker run -p 8080:8080 ghcr.io/mitulshah1/golang-rest-api-template:latest

Local Release Testing

Test the release process locally:

# Install GoReleaser
go install github.com/goreleaser/goreleaser@latest

# Test release (without publishing)
goreleaser release --snapshot --clean

Deployment

The project includes:

• Dockerfile for containerization
• docker-compose.yml for local development
• GitHub Actions for CI/CD pipeline
• GoReleaser for automated releases

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details