# API Instructions

## Scope
- Applies to Fiber handlers and route registration under `internal/handlers` and `internal/server/routes.go`.

## Rules
- Keep API contracts stable; if changing request/response shape, document backward compatibility in PR notes.
- Prefer snake_case JSON request fields for backend payloads and accept legacy aliases only when needed.
- Validate required fields explicitly in handlers and return clear `400` errors with actionable messages.
- Return `404` for missing resources, `500` only for unexpected server/database failures.
- Keep route naming consistent (`/resource`, `/resource/:id`) and group related routes in `routes.go`.

## Implementation Notes
- Use `database.DB()` directly in handlers unless a service layer exists for that feature.
- Preload only required relations for performance-sensitive list endpoints.
- Keep list endpoints sorted deterministically (e.g., `position asc, id asc`).