Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-api

golang-gin-api

Verified

Build REST APIs with Go Gin. Use when creating Go web servers, adding Gin routes, writing handlers, or asking about middleware, binding, error handling, or project structure.

FileKindSize
SKILL.mdskill md10.0 KB
metadata.jsonconfig482 B
references/background-jobs-goroutine-and-pool.mdmarkdown3.5 KB
references/background-jobs-queue-and-shutdown.mdmarkdown3.5 KB
references/defensive-handler-patterns.mdmarkdown3.7 KB
references/error-handling-apperror.mdmarkdown4.1 KB
references/error-handling-recovery.mdmarkdown1.8 KB
references/error-handling-validation.mdmarkdown3.0 KB
references/file-uploads-cloud.mdmarkdown2.4 KB
references/file-uploads-local.mdmarkdown4.0 KB
references/middleware-core.mdmarkdown4.2 KB
references/middleware-logging-and-recovery.mdmarkdown3.3 KB
references/middleware-timeout-and-custom.mdmarkdown3.2 KB
references/rate-limiting-algorithms.mdmarkdown3.5 KB
references/rate-limiting-fallback.mdmarkdown2.3 KB
references/rate-limiting-headers.mdmarkdown1.8 KB
references/rate-limiting-peruser.mdmarkdown2.4 KB
references/rate-limiting-redis-sliding.mdmarkdown2.2 KB
references/rate-limiting-redis.mdmarkdown2.9 KB
references/rate-limiting-sliding-window.mdmarkdown2.2 KB
references/rate-limiting-tiered.mdmarkdown3.0 KB
references/routing-groups-and-versioning.mdmarkdown3.8 KB
references/routing-params-and-wildcards.mdmarkdown3.4 KB
references/routing-validators-and-limits.mdmarkdown2.4 KB
references/safe-context-extraction.mdmarkdown4.3 KB
references/server-handlers-and-errors.mdmarkdown3.6 KB
references/server-setup-and-routes.mdmarkdown3.9 KB
references/websocket-auth-and-keepalive.mdmarkdown3.5 KB
references/websocket-chat-handler.mdmarkdown1.5 KB
references/websocket-hub-and-client.mdmarkdown3.9 KB
references/websocket-setup-and-echo.mdmarkdown3.4 KB
references/websocket-shutdown-and-messages.mdmarkdown3.8 KB
references/websocket-testing.mdmarkdown3.8 KB

references/routing-groups-and-versioning.md

View on GitHub
# Routing — Groups, Nesting & API Versioning

See also: `routing-params-and-wildcards.md`, `routing-validators-and-limits.md`

## Route Groups & Nesting

Groups share a path prefix and optional middleware. Use `{}` blocks for readability — they are cosmetic only (Go scope, not Gin scope).

```go
func registerRoutes(r *gin.Engine, h *handler.Handlers) {
    r.GET("/health", h.Health.Check)

    api := r.Group("/api")
    {
        v1 := api.Group("/v1")
        {
            auth := v1.Group("/auth")
            {
                auth.POST("/login", h.Auth.Login)
                auth.POST("/register", h.Auth.Register)
                auth.POST("/refresh", h.Auth.Refresh)
            }

            users := v1.Group("/users")
            users.Use(middleware.Auth(tokenCfg, logger))
            {
                users.GET("", h.User.List)
                users.POST("", h.User.Create)
                users.GET("/:id", h.User.GetByID)
                users.PUT("/:id", h.User.Update)
                users.DELETE("/:id", h.User.Delete)
            }

            admin := v1.Group("/admin")
            admin.Use(middleware.Auth(tokenCfg, logger), middleware.RequireRole("admin"))
            {
                admin.GET("/users", h.Admin.ListAllUsers)
                admin.DELETE("/users/:id", h.Admin.DeleteUser)
            }
        }
    }
}
```

**Why group nesting:** Each level applies its middleware to all routes below. This avoids repeating middleware on every route and makes the security model explicit in structure.

---

## API Versioning

### URL Path Versioning (recommended)

Path versioning is explicit, cache-friendly, and easy to route at the load-balancer level.

```go
v1 := r.Group("/api/v1")
v2 := r.Group("/api/v2")

v1.GET("/users", listUsersV1)
v2.GET("/users", listUsersV2)
```

### Header-Based Versioning

Use when you want a stable URL but need to evolve the API contract.

```go
// pkg/middleware/version.go
func APIVersion() gin.HandlerFunc {
    return func(c *gin.Context) {
        version := c.GetHeader("API-Version")
        if version == "" {
            version = "v1"
        }
        c.Set("api_version", version)
        c.Next()
    }
}

func listUsers(c *gin.Context) {
    version := c.GetString("api_version")
    switch version {
    case "v2":
        // return v2 shape
    default:
        // return v1 shape
    }
}
```

```go
r.Use(middleware.APIVersion())
r.GET("/api/users", listUsers)
```

---

## Query Parameter Binding with Pagination

Bind all query parameters at once using `ShouldBindQuery`. Define defaults via struct field initialisation before binding.

```go
// internal/domain/pagination.go
type ListOptions struct {
    Page   int    `form:"page"   binding:"min=1"`
    Limit  int    `form:"limit"  binding:"min=1,max=100"`
    Sort   string `form:"sort"   binding:"omitempty,oneof=created_at updated_at name"`
    Order  string `form:"order"  binding:"omitempty,oneof=asc desc"`
    Search string `form:"search" binding:"omitempty,max=100"`
    Role   string `form:"role"   binding:"omitempty,oneof=admin user"`
}

func (o *ListOptions) SetDefaults() {
    if o.Page == 0  { o.Page = 1 }
    if o.Limit == 0 { o.Limit = 20 }
    if o.Sort == ""  { o.Sort = "created_at" }
    if o.Order == "" { o.Order = "desc" }
}
```

```go
func (h *UserHandler) List(c *gin.Context) {
    var opts domain.ListOptions
    opts.SetDefaults()

    if err := c.ShouldBindQuery(&opts); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    users, total, err := h.svc.List(c.Request.Context(), opts)
    if err != nil {
        handleServiceError(c, err, h.logger)
        return
    }

    c.JSON(http.StatusOK, gin.H{
        "data":  users,
        "total": total,
        "page":  opts.Page,
        "limit": opts.Limit,
    })
}
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall