#🔷 Go Stateful HTTP API Blueprint

A reusable, contract‑first stateful HTTP API template built with pure Go (net/http) and a feature‑based layered architecture. Every feature follows the same pattern: controller → service → repository → model → mapper → dto. The API contract (OpenAPI 3.0) is the single source of truth – all code is generated from it.

⚠️ the project started as REST API in version 1.0.0.

⚠️ This version v4.0.0 is a stateful HTTP API, not REST. Server‑side state (Redis) is intentionally used for refresh token rotation, rate limiting, OTP storage and session endpoints – all of which violate REST’s statelessness constraint.

#Quick Start with Docker

Run the pre‑built Docker image from Docker Hub:

docker pull adnenrebai/rest-api-blueprint:v4.0.0
docker run -p 8080:8080 adnenrebai/rest-api-blueprint:v4.0.0

Then test the health endpoint:

curl http://localhost:8080/api/v1/health

Open your browser at http://localhost:8080/docs/ to explore the interactive Swagger UI documentation.

#✨ Key Features

• ✅ Contract‑first – Define the API in openapi.yaml, then generate type‑safe server stubs.
• ✅ No external web framework – Only the standard library (net/http) and a code generator.
• ✅ Feature‑based layered architecture – Each feature is isolated, making it easy to scale or split into microservices later.
• ✅ Enterprise‑ready health endpoint – Real checks for PostgreSQL and Redis, returns 200/503 with detailed checks map.
• ✅ Dual‑mode authentication – Supports both httpOnly cookies (secure web BFF) and Authorization: Bearer headers (mobile apps) from the same endpoints.
• ✅ Refresh token rotation – One‑time use refresh tokens stored in Redis, automatically rotated on each refresh request.
• ✅ Session endpoint – GET /api/v1/auth/session returns current user without a separate profile request.
• ✅ JWT authentication with OTP verification – Register, login, email‑based OTP activation and password reset flows.
• ✅ User profile & preferences – GET /users/me and PATCH /users/me/preferences.
• ✅ Admin user management – Full CRUD on users (/admin/users) with role‑based access (admin only).
• ✅ Distributed rate limiting – Redis‑based token bucket, per client IP, returns 429 with Retry-After headers.
• ✅ Request correlation – X-Request-Id header automatically generated, stored in context and logged.
• ✅ CORS & security headers – Configurable CORS, plus extensive security headers.
• ✅ RFC 7807 error handling – Standardised application/problem+json error responses.
• ✅ Global request validation – Automatic DTO validation with field‑specific RFC 7807 errors.
• ✅ Structured JSON logging – log/slog with request ID, method, path, status, latency.
• ✅ Docker Compose – Full stack (PostgreSQL, Redis, Go app) with hot reload (air).
• ✅ GitHub Actions CI/CD – Tests with service containers, builds and pushes Docker image on tags.
• ✅ OpenAPI UI – Swagger documentation embedded in the binary.
• ✅ Makefile – Automates generation, scaffolding, running, testing and Docker management.
• ✅ Microservice‑ready – Designed to be deployed as a monolith today and split into microservices tomorrow with minimal refactoring.

#🛠️ Tech Stack