What is Gin?

Every HTTP request that hits a Grit API passes through Gin. Before you can write or change a route, you need a feel for what Gin is, what it does for you, and what you have to do yourself.

What is Gin?

Gin is a small, fast HTTP web framework for Go. It does three jobs:

• Routes URLs to functions you write (GET /api/users → ListUsers).
• Parses the request (path params, query, body, headers) into Go values.
• Serializes your response (struct → JSON, with the right status code).

Without Gin you would write net/http by hand and parse JSON manually for every endpoint. Gin removes 90% of that ceremony while staying thin enough to read in an afternoon.

The request lifecycle

The smallest possible Gin server

package main

import "github.com/gin-gonic/gin"

func main() {
    r := gin.Default()                   // 1. new router with sensible defaults
    r.GET("/ping", func(c *gin.Context) { // 2. register a route
        c.JSON(200, gin.H{"message": "pong"})  // 3. write response
    })
    r.Run(":8080")                       // 4. start listening
}

Four lines worth understanding:

• gin.Default() gives you a router with the logger and panic-recovery middleware pre-attached. Grit uses this.
• r.GET registers a handler for a method+path. There's also POST, PATCH, DELETE, etc.
• c *gin.Context is the most important type in Gin. It bundles request + response + middleware data. Every handler gets one.
• c.JSON(status, body) serializes the body as JSON and sets the status code. Done.

How a Grit project wires it up

func Register(r *gin.Engine, s *Services) {
  // Health (public)
  r.GET("/healthz", s.HealthHandler.Check)

  // All API endpoints under /api
  api := r.Group("/api")

  // Public auth endpoints
  api.POST("/auth/register", s.AuthHandler.Register)
  api.POST("/auth/login",    s.AuthHandler.Login)

  // Everything below requires an auth token
  authed := api.Group("")
  authed.Use(middleware.RequireAuth(s.JWT))

  authed.GET("/users",       s.UserHandler.List)
  authed.GET("/users/:id",   s.UserHandler.Get)
  authed.PATCH("/users/:id", s.UserHandler.Update)
}

Three things to notice:

• Groups. r.Group("/api") factors out a common prefix. Cleaner than typing it on every line.
• Middleware on groups. authed.Use(middleware.RequireAuth(...)) applies the auth gate to ONLY routes registered after that call. Public ones above stay open.
• Path params with :id. Gin parses these for you — read with c.Param("id") inside the handler.

Reading input — the c.* family

func (h *UserHandler) Get(c *gin.Context) {
  id := c.Param("id")                           // /users/:id
  q  := c.Query("expand")                       // ?expand=profile
  page := c.DefaultQuery("page", "1")           // ?page= (default "1")

  var input UpdateUserInput
  if err := c.ShouldBindJSON(&input); err != nil {
    c.JSON(400, gin.H{"error": err.Error()})    // body parse failed
    return
  }

  authedID := c.GetUint("user_id")              // set by RequireAuth middleware
}

Five lookups, five different sources. Memorise these — you'll type them dozens of times:

• c.Param — URL placeholder (:id).
• c.Query — querystring (?key=v).
• c.ShouldBindJSON — JSON request body → struct.
• c.GetUint / GetString — value set by middleware.
• c.GetHeader — HTTP header.

Writing output — c.JSON, c.AbortWithStatusJSON

// Success — standard Grit envelope
c.JSON(200, gin.H{"data": user, "message": "ok"})

// Error — stops middleware chain AND writes
c.AbortWithStatusJSON(404, gin.H{"error": gin.H{
  "code": "not_found",
  "message": "User not found",
}})

Use Abort when something has gone wrong — it stops any downstream middleware from running. c.JSON alone keeps the chain going (rarely what you want for errors).

Middleware in 10 lines

func RequireAuth(jwtSvc *JWTService) gin.HandlerFunc {
  return func(c *gin.Context) {
    token := c.GetHeader("Authorization")
    if token == "" {
      c.AbortWithStatusJSON(401, gin.H{"error": "missing token"})
      return
    }
    claims, err := jwtSvc.Verify(strings.TrimPrefix(token, "Bearer "))
    if err != nil {
      c.AbortWithStatusJSON(401, gin.H{"error": "bad token"})
      return
    }
    c.Set("user_id", claims.UserID)  // available downstream via c.GetUint("user_id")
    c.Next()                          // continue to the handler
  }
}

A middleware IS just a handler that calls c.Next() when it wants the chain to continue. Authentication, rate limiting, request logging, request ID — all the same shape.

What's next

Next lesson — GORM. The ORM that turns Go structs into SQL. Once Gin gets the request to a handler and the handler calls a service, the service uses GORM to actually read/write the database.