https://github.com/jmrashed/golang-rest-api-with-mysql
golang-rest-api-with-mysql
https://github.com/jmrashed/golang-rest-api-with-mysql
Last synced: 15 days ago
JSON representation
golang-rest-api-with-mysql
- Host: GitHub
- URL: https://github.com/jmrashed/golang-rest-api-with-mysql
- Owner: jmrashed
- Created: 2023-04-30T18:14:32.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-10-06T04:35:37.000Z (9 months ago)
- Last Synced: 2025-10-06T06:28:02.112Z (9 months ago)
- Language: Go
- Size: 377 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# RESTful API in GO with Enhanced Authentication & Authorization
This is an advanced Go project featuring a comprehensive authentication and authorization system with JWT tokens, role-based access control (RBAC), and permission-based access control. The API is designed with clean architecture principles and includes extensive testing.
## 🚀 Features
### Authentication & Authorization
- **JWT-based Authentication**: Stateless authentication with access and refresh tokens
- **Role-Based Access Control (RBAC)**: Users have roles that determine access levels
- **Permission-Based Access Control**: Fine-grained permissions for specific actions
- **Secure Password Hashing**: bcrypt for password security
- **Token Refresh**: Automatic token renewal without re-authentication
- **Multi-device Logout**: Support for logging out from all devices
### Security Features
- **Password Validation**: Strong password requirements
- **Token Expiration**: Access tokens (15 min), refresh tokens (7 days)
- **Secure Token Storage**: Hashed refresh tokens in database
- **Input Validation**: Comprehensive request validation
- **Error Handling**: Structured error responses
- **CORS Support**: Cross-origin resource sharing
### Architecture & Testing
- **Clean Architecture**: Separation of concerns with layers
- **Comprehensive Testing**: Unit and integration tests
- **Database Migrations**: Automated schema initialization
- **Environment Configuration**: Flexible configuration management
- **API Documentation**: Complete endpoint documentation
### Performance & Scalability
- **Rate Limiting**: Protection against API abuse (60 req/min)
- **Caching**: In-memory caching for improved performance
- **Pagination**: Efficient data retrieval with filtering and sorting
- **Database Indexing**: Optimized database queries
- **Connection Pooling**: Efficient database connection management
### Development & Deployment
- **Docker Support**: Containerized deployment
- **CI/CD Pipeline**: Automated testing and deployment
- **Health Monitoring**: Comprehensive health checks
- **Logging**: Structured request/response logging
- **OpenAPI Documentation**: Swagger/OpenAPI 3.0 specification
### Technology Stack
- **Routing**: [Gorilla Mux](https://github.com/gorilla/mux)
- **Database**: [MySQL Driver](https://github.com/go-sql-driver/mysql)
- **JWT**: [jwt-go](https://github.com/dgrijalva/jwt-go)
- **Password Hashing**: [bcrypt](https://golang.org/x/crypto/bcrypt)
- **Validation**: [validator/v10](https://github.com/go-playground/validator)
- **Testing**: [Testify](https://github.com/stretchr/testify)
- **UUID**: [Google UUID](https://github.com/google/uuid)
## 🛠️ Getting Started
### Prerequisites
- [Go 1.16+](https://golang.org/doc/install)
- [MySQL 5.7+](https://dev.mysql.com/downloads/mysql/)
- [Git](https://git-scm.com/downloads)
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/jmrashed/golang-rest-api-with-mysql.git
cd golang-rest-api-with-mysql
```
2. **Install dependencies**
```bash
go mod tidy
```
3. **Set up environment variables**
```bash
cp .env.example .env
# Edit .env with your database credentials and JWT secrets
```
4. **Set up MySQL database**
```sql
CREATE DATABASE goblog;
```
5. **Run the application**
```bash
# Development
go run main.go
# Or using Make
make run
# Or using Docker
docker-compose up -d
```
The server will start on `http://localhost:8080`
### Quick Start with Docker
```bash
# Clone and start with Docker
git clone https://github.com/jmrashed/golang-rest-api-with-mysql.git
cd golang-rest-api-with-mysql
cp .env.example .env
docker-compose up -d
```
## 📚 API Endpoints
### Public Endpoints
- `POST /api/v1/register` - User registration
- `POST /api/v1/login` - User authentication
- `POST /api/v1/refresh` - Token refresh
- `GET /health` - Health check
### Protected Endpoints (Authentication Required)
- `GET /api/v1/profile` - Get user profile
- `PUT /api/v1/profile` - Update user profile
- `POST /api/v1/change-password` - Change password
- `POST /api/v1/logout` - Logout from current session
- `POST /api/v1/logout-all` - Logout from all sessions
### Role-Based Endpoints
- `/api/v1/admin/*` - Admin only endpoints
- `/api/v1/moderator/*` - Moderator and admin endpoints
- `/api/v1/todos/*` - Permission-based todo endpoints
For detailed API documentation, see [API_DOCUMENTATION.md](API_DOCUMENTATION.md)
## 🧪 Testing with Postman
### Environment Setup
1. Create a new Postman environment
2. Add variables:
- `baseUrl`: `http://localhost:8080/api/v1`
- `accessToken`: (will be set automatically)
- `refreshToken`: (will be set automatically)
### Auto-Token Management
Add this script to the **Tests** tab of login and register requests:
```javascript
if (pm.response.code === 200 || pm.response.code === 201) {
const response = pm.response.json();
if (response.data && response.data.access_token) {
pm.environment.set('accessToken', response.data.access_token);
pm.environment.set('refreshToken', response.data.refresh_token);
}
}
```
### Authorization Header
For protected endpoints, set Authorization header to:
```
Bearer {{accessToken}}
```
## 🔧 cURL Examples
### User Registration
```bash
curl -X POST http://localhost:8080/api/v1/register \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"email": "test@example.com",
"password": "password123"
}'
```
### User Login
```bash
curl -X POST http://localhost:8080/api/v1/login \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"password": "password123"
}'
```
### Get User Profile (Protected)
```bash
curl -X GET http://localhost:8080/api/v1/profile \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
### Refresh Token
```bash
curl -X POST http://localhost:8080/api/v1/refresh \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "YOUR_REFRESH_TOKEN"
}'
```
## 📁 Project Structure
```
.
├── auth/ # Authentication utilities
├── database/ # Database connection and configuration
├── handlers/ # HTTP request handlers
├── middleware/ # Authentication and authorization middleware
├── model/ # Data models and DTOs
├── repository/ # Data access layer
├── route/ # Route definitions and setup
├── schema/ # Database schema and migrations
├── service/ # Business logic layer
├── static/ # Static files
├── .env.example # Environment variables template
├── API_DOCUMENTATION.md # Detailed API documentation
└── main.go # Application entry point
```
## 🔐 Authentication & Authorization System
### JWT Token Structure
The system uses two types of tokens:
**Access Token** (15 minutes):
```json
{
"user_id": 1,
"username": "testuser",
"email": "test@example.com",
"roles": ["user"],
"permissions": ["read_todos", "write_todos"],
"exp": 1640995200
}
```
**Refresh Token** (7 days):
```json
{
"user_id": 1,
"jti": "unique-token-id",
"exp": 1641600000
}
```
### Middleware Chain
1. **CORS Middleware**: Handles cross-origin requests
2. **Auth Middleware**: Validates JWT tokens
3. **Role Middleware**: Checks user roles
4. **Permission Middleware**: Validates specific permissions
### Role-Based Access Control
- **Admin**: Full system access
- **Moderator**: Content management access
- **User**: Basic user operations
### Permission System
Fine-grained permissions for specific actions:
- `read_users`, `write_users`, `delete_users`
- `read_todos`, `write_todos`, `delete_todos`
- `manage_roles`
## 🗄️ Database Schema
The system uses a comprehensive database schema with the following tables:
- **users**: User account information
- **roles**: System roles (admin, user, moderator)
- **permissions**: Granular permissions
- **user_roles**: User-role assignments
- **role_permissions**: Role-permission assignments
- **refresh_tokens**: Secure token storage
For detailed schema, see [schema/schema.sql](schema/schema.sql)
## 🧪 Testing
### Run Unit Tests
```bash
# Individual packages
go test ./auth -v
go test ./middleware -v
go test ./handlers -v
# Or using Make
make test
```
### Run All Tests
```bash
# All tests with race detection
go test ./... -v -race
# With coverage
make test-coverage
```
### Test Coverage
```bash
# Generate coverage report
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html
# Or using Make
make test
```
### End-to-End Tests
```bash
# Run E2E tests
go test ./tests -v
```
### Performance Testing
```bash
# Load testing with Apache Bench
ab -n 1000 -c 10 http://localhost:8080/health
# Or with curl for rate limiting
for i in {1..70}; do curl http://localhost:8080/health; done
```
## 🚀 Deployment
### Environment Variables
Copy `.env.example` to `.env` and configure:
- Database credentials
- JWT secrets (use strong, random keys)
- Server configuration
### Docker Deployment
```bash
# Build and run with Docker Compose
docker-compose up -d
# Or build manually
docker build -t golang-rest-api .
docker run -p 8080:8080 golang-rest-api
```
### Production Deployment
```bash
# Build for production
make prod-build
# Run database migration
make migrate
# Start the application
./build/golang-rest-api
```
### Production Considerations
- Use environment-specific JWT secrets
- Enable HTTPS with reverse proxy (nginx/traefik)
- Configure proper CORS origins
- Set up database connection pooling
- Implement monitoring and alerting
- Use container orchestration (Kubernetes/Docker Swarm)
- Set up log aggregation (ELK stack)
- Configure backup strategies
### Monitoring
- **Health Check**: `GET /health`
- **Metrics**: Application logs and performance metrics
- **Database**: Connection pool monitoring
- **Rate Limiting**: Request rate monitoring
## 🛠️ Development
### Available Make Commands
```bash
make help # Show all available commands
make dev-setup # Setup development environment
make build # Build the application
make run # Run the application
make test # Run tests with coverage
make lint # Run code linter
make security # Run security scan
make docker-build # Build Docker image
make docker-run # Run with Docker Compose
make clean # Clean build artifacts
```
### Code Quality
```bash
# Run linter
golangci-lint run
# Security scan
gosec ./...
# Format code
go fmt ./...
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run tests and linting (`make test && make lint`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Submit a pull request
### Development Guidelines
- Follow Go best practices and idioms
- Write comprehensive tests for new features
- Update documentation for API changes
- Use meaningful commit messages
- Ensure all CI checks pass
## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
## 📊 Performance Metrics
- **Response Time**: < 100ms for most endpoints
- **Throughput**: 1000+ requests/second
- **Rate Limiting**: 60 requests/minute per IP
- **Cache Hit Rate**: 80%+ for cached endpoints
- **Database Connections**: Pool of 25 connections
## 🔍 API Documentation
- **Swagger UI**: Available at `/docs` (when implemented)
- **OpenAPI Spec**: [docs/swagger.yaml](docs/swagger.yaml)
- **Postman Collection**: Import the API endpoints
- **cURL Examples**: See README sections above
## 🆘 Support
For questions and support:
- Create an issue on GitHub
- Check the [API Documentation](API_DOCUMENTATION.md)
- Review the [OpenAPI Specification](docs/swagger.yaml)
- Review the test files for usage examples
- Check the [Makefile](Makefile) for development commands