Skip to content

Home

GRAB Logo

Go REST API Boilerplate

Grab it and Go — a clean, production-ready REST API starter kit in Go with JWT, PostgreSQL, Docker, and Swagger.

Version License Go Version

🚀 Main Repository | 📋 Changelog | 🐛 Report Issues

🎯 Why GRAB?

Building a REST API in Go shouldn't take days of setup. GRAB gives you a production-ready foundation so you can focus on building features, not infrastructure.

The Problem We Solve

When starting a new Go REST API project, you typically spend days: - 🔧 Setting up project structure and deciding on architecture - 🔐 Implementing authentication and security - 🐳 Configuring Docker, hot-reload, and development environment - 📚 Setting up API documentation and testing tools - 🗄️ Configuring database, migrations, and ORM - ✅ Writing tests and CI/CD pipelines

The GRAB Solution

One command. Two minutes. Production-ready.

make quick-start

That's it. You get a fully configured, battle-tested REST API with:

  • ✅ Clean Architecture - Layered structure that scales
  • ✅ JWT Authentication - Secure, ready to use
  • ✅ Hot-Reload Development - See changes in 2 seconds
  • ✅ Database Migrations - Version-controlled schema
  • ✅ Interactive API Docs - Swagger UI out of the box
  • ✅ Automated Tests - Unit and integration tests
  • ✅ Docker-First - Consistent environments
  • ✅ Production Optimized - Multi-stage builds, security best practices

✨ Features

  • JWT Authentication

    Secure token-based authentication with HS256 algorithm and bcrypt password hashing

  • User Management

    Complete CRUD operations with validation and error handling

  • PostgreSQL + GORM

    Robust database with powerful ORM and automated migrations

  • Docker Development

    Hot-reload with Air (~2 sec feedback), volume mounting for live code sync

  • Production Ready

    Optimized multi-stage Docker builds, minimal Alpine images

  • Swagger/OpenAPI

    Interactive API documentation with "Try it out" feature

  • Database Migrations

    Version-controlled schema changes with golang-migrate

  • Automated Testing

    Unit & integration tests with 75%+ coverage

  • GitHub Actions CI

    Automated linting, testing, and code quality checks

  • Make Commands

    Simplified workflow automation with auto-detection (Docker/host)

  • Postman Collection

    Pre-configured API tests with example requests

  • Clean Architecture

    Layered, maintainable structure (Handler → Service → Repository)

  • Security Best Practices

    Bcrypt hashing, input validation, SQL injection protection

  • CORS Support

    Configurable cross-origin requests for frontend integration

  • Code Quality

    golangci-lint configured with best practices

🚀 Perfect For

  • Starting New Projects

    Skip the setup headache and start building features immediately

  • Learning Go Web Development

    Production-quality examples and best practices to learn from

  • Building Scalable APIs

    Architecture that grows with your application

  • Team Projects

    Consistent structure and standards that everyone can follow

  • Rapid Prototyping

    Get your MVP running in minutes, not days

  • Enterprise Applications

    Battle-tested patterns and security best practices

🎬 Quick Start

Get your API running in under 2 minutes:

# Clone the repository
git clone https://github.com/vahiiiid/go-rest-api-boilerplate.git
cd go-rest-api-boilerplate

# One command to rule them all
make quick-start

🎉 Done! Your API is now running at:

  • API Base URL: http://localhost:8080/api/v1
  • Swagger UI: http://localhost:8080/swagger/index.html
  • Health Check: http://localhost:8080/health

➡️ Full Setup Guide for more options (manual setup, production deployment)

📖 What's Next?

🏗️ Architecture

GRAB follows clean architecture principles with clear separation of concerns:

┌─────────────────────────────────────┐
│         Handler Layer               │  ← HTTP handlers, request/response
│   (internal/user/handler.go)        │     validation, error handling
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│         Service Layer               │  ← Business logic, orchestration
│   (internal/user/service.go)        │     transactions, domain rules
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│       Repository Layer              │  ← Data access, CRUD operations
│  (internal/user/repository.go)      │     database queries
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│         Database (PostgreSQL)       │  ← Data persistence
└─────────────────────────────────────┘

Key Principles

  • ✅ Separation of Concerns - Each layer has a single responsibility
  • ✅ Dependency Injection - Loose coupling between layers
  • ✅ Testability - Easy to mock and test each layer
  • ✅ Maintainability - Clear structure, easy to navigate
  • ✅ Scalability - Easy to extend with new features

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

📄 License

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

Made with ❤️ for the Go community

⭐ Star this repo if you find it useful!