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.