api-endpoint-pattern

API Endpoint Pattern Skill

Use this skill when adding or modifying HTTP endpoints in the API.

---

Scope

• Creating new API endpoints
• Adding new domain routers
• Modifying handler logic

---

Router Structure

Main Router (internal/​router/​router.go)

Initializes Echo, sets up middleware, and groups routes by domain.

Sub-Routers (internal/​router/[domain]/​router.go)

Each domain has its own sub-router with a Bind function that receives an *echo.Group and dependencies.

func Bind(e *echo.Group, db *sql.DB) *echo.Group {
    e.GET("/​list", func(c echo.Context) error {
        // handler logic
    })
    return e
}

---

Adding a New Endpoint

1. If introducing a new domain, create internal/​router/[domain]/​router.go.
2. Implement a Bind(e *echo.Group, db *sql.DB) *echo.Group function.
3. Register the sub-router in internal/​router/​router.go:

   domainrouter.Bind(api.Group("/​domain"), config.DB.Conn)
   

4. Implement data access logic in internal/​models/ if needed.

---

Handler Guidelines

• Parameter Parsing: Use helper functions for complex query params (e.g., trader levels).
• Dependency Injection: Pass *sql.DB into Bind, then into handlers. Avoid globals.
• Response Handling:
  • Success: c.JSON(200, data) or c.String(200, "OK")
  • Error: c.String(code, err.Error()) — log significant errors with zerolog.
• Business Logic: Keep handlers thin. Move complex logic to internal/​models/ or other internal packages.

---

Conventions

• Use e.Group() for logical route separation.
• Use plural names for collections (/​items, /​weapons).
• Use query parameters for filtering and optional configuration.
• Prefer HTTP status constants for consistency, but be consistent either way.