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

• If introducing a new domain, create internal/router/[domain]/router.go .

• Implement a Bind(e *echo.Group, db *sql.DB) *echo.Group function.

• Register the sub-router in internal/router/router.go : domainrouter.Bind(api.Group("/domain"), config.DB.Conn)

• 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.