Golang Web API

Conventions for Go web API development. These apply for the entire session once activated.

Recommended model: Sonnet

Includes all standards from the api-design skill.

Package and Layer Structure

Three layers per feature, each in its own file:

internal/
  users/
    handler.go      # HTTP: parse request, call service, write response
    service.go      # Business logic: no HTTP, no SQL
    repository.go   # DB: raw queries only
    types.go        # Domain types, request/response structs
  shared/
    response/
      response.go   # JSON response helpers
    middleware/
      auth.go
      logging.go
    errors/
      errors.go     # AppError, sentinel errors
cmd/
  api/
    main.go

Handler (thin): Decode request → validate → call service → encode response. No business logic.

Service: Pure business rules. No http.Request/http.ResponseWriter. No SQL. Returns domain types and errors.

Repository: SQL/DB only. No business rules. Takes context.Context as first arg.

Error Handling

Always wrap errors with context:

// In repository
return nil, fmt.Errorf("userRepo.FindByID: %w", err)

// In service
return nil, fmt.Errorf("userService.GetUser: %w", err)

Define typed errors for domain conditions:

var ErrNotFound = errors.New("not found")
var ErrConflict = errors.New("conflict")

type ValidationError struct {
    Field   string
    Message string
}
func (e *ValidationError) Error() string { return fmt.Sprintf("%s: %s", e.Field, e.Message) }

Use errors.Is() and errors.As() in handlers to map to HTTP status codes — never do this in services.

Interfaces and Dependency Injection

• Accept interfaces, return concrete types
• Define interfaces where they are used (not where implemented)
• Inject all dependencies via struct fields; no global state

type UserRepository interface {
    FindByID(ctx context.Context, id string) (*User, error)
    Create(ctx context.Context, input CreateUserInput) (*User, error)
}

type UserService struct {
    repo   UserRepository
    logger *slog.Logger
}

func NewUserService(repo UserRepository, logger *slog.Logger) *UserService {
    return &UserService{repo: repo, logger: logger}
}

Context

• context.Context is the first parameter of every service and repository method
• Propagate context from handler through to DB call — never discard it
• Use context.WithTimeout for external calls

HTTP Layer

• Prefer net/http stdlib + chi router
• Avoid heavy frameworks (no gin, no echo — keep it replaceable)
• Use chi.URLParam(r, "id") for path params
• Decode JSON body: json.NewDecoder(r.Body).Decode(&input) — always check error

Validation

Use go-playground/validator struct tags:

type CreateUserInput struct {
    Email string `json:"email" validate:"required,email"`
    Name  string `json:"name"  validate:"required,min=1,max=100"`
}

Validate in handler before calling service:

if err := validate.Struct(input); err != nil {
    // map to 400 response
}

Response Helpers

Use a shared package — never build envelope inline:

// internal/shared/response/response.go
func JSON(w http.ResponseWriter, status int, data any) { ... }
func Error(w http.ResponseWriter, status int, code, message string) { ... }

Logging

Use log/slog (stdlib, Go 1.21+):

slog.InfoContext(ctx, "user created", "userID", user.ID, "requestID", r.Header.Get("X-Request-Id"))

Log at service/handler boundary only. Repositories should not log.

Graceful Shutdown

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
// start server, then wait on ctx.Done()

Concurrency

• Use errgroup.Group for parallel work with error aggregation
• Avoid raw goroutines without a WaitGroup or channel for synchronization
• Always pass context.Context to goroutine work for cancellation

What NOT to do

• No global variables for dependencies (db, logger, config) — inject via structs
• No bare errors.New("something") in service or repository without wrapping caller context
• No business logic in handlers
• No SQL in services
• No http.Request passed to services
• No heavy frameworks replacing net/http
• Never discard context — always propagate