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.