Gin is the most popular HTTP web framework for Go, known for its speed and minimalist API. It provides a radix-tree-based router, middleware support, JSON rendering, request binding with validation, and structured error handling—all while maintaining compatibility with Go’s standard net/http interfaces. For teams building RESTful APIs in Go, Gin strikes the balance between having enough batteries included to be productive and staying close enough to the standard library to avoid framework lock-in.
The REST service uses Gin to build its API layer, handling request routing, input validation, authentication middleware, and structured JSON responses. Gin’s context-based design maps cleanly to the request-per-goroutine model: each handler receives a *gin.Context that carries the request, response writer, path parameters, validated input, and any values set by upstream middleware.
Understanding Gin means understanding three things: how the router maps URLs to handlers, how middleware chains process requests before and after handlers, and how request binding turns raw HTTP input into validated Go structs. These three mechanisms cover 90% of what you need for a production API.
Gin uses a radix tree (compressed trie) for URL routing, which gives O(k) lookup time where k is the length of the URL path. Unlike regex-based routers, the radix tree doesn’t slow down as you add routes. It supports path parameters (/users/:id), wildcard parameters (/files/*filepath), and automatic 405 Method Not Allowed responses for paths that exist but with a different HTTP method.
The *gin.Context is the central object passed to every handler and middleware. It wraps the HTTP request and response writer, provides methods for reading parameters, binding input, writing JSON, and setting/getting values for middleware communication. It also manages the middleware chain through c.Next() (continue to next handler) and c.Abort() (stop the chain).
Gin’s binding system automatically deserializes request bodies (JSON, XML, form data) into Go structs and validates them using struct tags. The binding:"required" tag ensures a field is present; additional validators check formats, ranges, and patterns. If binding fails, Gin returns the validation errors as a structured response, so handlers never need to manually parse or validate raw input.
Route groups let you apply a common URL prefix and middleware set to a collection of routes. The /api/v1 group gets auth middleware; the /admin group gets auth plus admin-role middleware; the /health group gets no middleware at all. Groups nest, so you can build a hierarchy: v1 > authenticated > admin.
Gin middleware functions have the same signature as handlers (func(*gin.Context)). Calling c.Next() executes the remaining handlers in the chain; code after c.Next() runs on the way back (response phase). Calling c.Abort() stops the chain, preventing downstream handlers from executing. This gives middleware full control over whether and when the request proceeds.
A Gin application starts with an engine (router), registers routes and middleware, then starts listening. The engine is an http.Handler, so it integrates with Go’s standard server, TLS configuration, and graceful shutdown patterns.
package main
import (
"net/http"
"github.com/gin-gonic/gin"
)
func main() {
r := gin.New()
r.Use(gin.Logger(), gin.Recovery())
// Public routes
r.GET("/health", func(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"status": "ok"})
})
// Authenticated API routes
api := r.Group("/api/v1")
api.Use(AuthMiddleware())
{
api.GET("/documents", listDocuments)
api.GET("/documents/:id", getDocument)
api.POST("/documents", createDocument)
api.PUT("/documents/:id", updateDocument)
api.DELETE("/documents/:id", deleteDocument)
}
r.Run(":8080")
}Gin’s ShouldBindJSON deserializes the request body into a struct and validates it in one step. Validation rules are declared as struct tags using the go-playground/validator library, which Gin includes by default. This keeps validation logic co-located with the data definition rather than scattered through handler code.
type CreateDocumentRequest struct {
Title string `json:"title" binding:"required,min=1,max=200"`
Content string `json:"content" binding:"required"`
Tags []string `json:"tags" binding:"max=10,dive,min=1,max=50"`
Type string `json:"type" binding:"required,oneof=article note snippet"`
}
func createDocument(c *gin.Context) {
var req CreateDocumentRequest
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{
"error": "validation_failed",
"details": formatValidationErrors(err),
})
return
}
doc, err := documentService.Create(c.Request.Context(), req)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "internal_error"})
return
}
c.JSON(http.StatusCreated, doc)
}
func formatValidationErrors(err error) map[string]string {
errors := make(map[string]string)
if ve, ok := err.(validator.ValidationErrors); ok {
for _, fe := range ve {
errors[fe.Field()] = fmt.Sprintf("failed on '%s' validation", fe.Tag())
}
}
return errors
}Path parameters (from the URL pattern) and query parameters (from the query string) are extracted through different gin.Context methods. Path parameters are always present if the route matched; query parameters are optional and need defaults.
func getDocument(c *gin.Context) {
id := c.Param("id") // from /documents/:id
doc, err := documentService.Get(c.Request.Context(), id)
if err != nil {
c.JSON(http.StatusNotFound, gin.H{"error": "not_found"})
return
}
c.JSON(http.StatusOK, doc)
}
func listDocuments(c *gin.Context) {
// Query parameters with defaults
page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
perPage, _ := strconv.Atoi(c.DefaultQuery("per_page", "20"))
sortBy := c.DefaultQuery("sort", "created_at")
filter := c.Query("filter") // empty string if not present
docs, total, err := documentService.List(c.Request.Context(), ListOptions{
Page: page,
PerPage: perPage,
SortBy: sortBy,
Filter: filter,
})
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "internal_error"})
return
}
c.JSON(http.StatusOK, gin.H{
"data": docs,
"total": total,
"page": page,
"per_page": perPage,
})
}Writing Gin middleware follows the same pattern as handlers. The function receives a *gin.Context, does its pre-processing, calls c.Next() to proceed, then does post-processing. Values passed between middleware use c.Set() and c.Get().
func AuthMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
token := c.GetHeader("Authorization")
if token == "" {
c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
"error": "missing authorization header",
})
return
}
// Strip "Bearer " prefix
if len(token) > 7 && token[:7] == "Bearer " {
token = token[7:]
}
claims, err := verifyToken(token)
if err != nil {
c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
"error": "invalid token",
})
return
}
c.Set("user_id", claims.Subject)
c.Set("user_email", claims.Email)
c.Next()
}
}
func RequestTimingMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
c.Next()
duration := time.Since(start)
c.Header("X-Response-Time", duration.String())
slog.Info("request completed",
"method", c.Request.Method,
"path", c.FullPath(),
"status", c.Writer.Status(),
"duration", duration,
)
}
}In the REST service, Gin serves as the API layer between the frontend and the backend services. Routes are organized into groups by domain: document management, search, user administration, and billing. Each group applies the appropriate middleware chain, and handlers are thin wrappers that bind input, call a service method, and render the response.
Gin’s compatibility with http.Handler means you can mount standard library handlers alongside Gin routes. The service mounts a pprof handler for profiling and a Prometheus metrics handler for monitoring, both as standard http.Handler implementations on separate route groups with their own access controls.
Define a consistent error response format and a helper function to emit it. Every error response should include a machine-readable error code, a human-readable message, and optionally field-level validation details. This makes it easy for frontend clients to display appropriate error messages.
Don’t use r.Run() in production—it doesn’t support graceful shutdown. Instead, create an http.Server with the Gin engine as its handler, and use server.Shutdown(ctx) to drain in-flight requests before exiting. This prevents dropped requests during deployments.
srv := &http.Server{
Addr: ":8080",
Handler: r,
}
go func() {
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Fatal(err)
}
}()
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
srv.Shutdown(ctx)Gin works with Go’s httptest package for handler testing. Create a test engine, register the route under test, and use httptest.NewRecorder to capture the response. This gives you fast, isolated tests without starting a real server.
gin.Default() includes the default logger that writes to stdout with color codes. Use gin.New() and add your own structured logger middleware that outputs JSON for log aggregation systems.c.Abort() or c.AbortWithStatusJSON(), the next handler still executes, potentially overwriting your error response or operating on invalid state.c.Bind() writes a 400 response automatically on failure, removing your control over the error format. Use c.ShouldBindJSON() instead and handle the error yourself.c.Request.Context() to downstream calls (database queries, HTTP clients). If the client disconnects, the context cancels, and your handler should stop work rather than completing a request nobody is waiting for.