---
phase: 05-template-data-model-and-api
plan: 02
subsystem: api
tags: [go, rest-api, templates, budget-generation, http-handlers]

requires:
  - phase: 05-template-data-model-and-api
    plan: 01
    provides: GetTemplate, CreateTemplateItem, UpdateTemplateItem, DeleteTemplateItem, ReorderTemplateItems, GenerateBudgetFromTemplate, BudgetExistsError

provides:
  - GET /api/template returns TemplateDetail (empty items when no template)
  - PUT /api/template updates template name
  - POST /api/template/items adds template item with validation (no one_off, fixed requires budgeted_amount)
  - PUT /api/template/items/{itemId} updates template item
  - DELETE /api/template/items/{itemId} removes template item (204)
  - PUT /api/template/items/reorder batch-updates sort order (204)
  - POST /api/budgets/generate creates budget from template or returns 409 with budget_id
  - CreateBudgetItem/UpdateBudgetItem handlers already accept item_tier (done in Plan 01 auto-fix)

affects:
  - 06 (frontend template UI will call these endpoints)

tech-stack:
  added: []
  patterns:
    - errors.As for typed BudgetExistsError detection in GenerateBudget handler
    - Static route /items/reorder registered before parameterized /items/{itemId} for correct chi routing
    - Handler-level validation mirrors DB CHECK constraint as defense in depth

key-files:
  created: []
  modified:
    - backend/internal/api/handlers.go
    - backend/internal/api/router.go

key-decisions:
  - "PUT /items/reorder registered before PUT /items/{itemId} to prevent chi treating 'reorder' as an itemId"
  - "GenerateBudget returns 409 JSON with both error message and budget_id field using BudgetExistsError.ExistingBudgetID"
  - "Handler validates month format via time.Parse before calling query layer (redundant but explicit)"

duration: 1min
completed: 2026-03-12
---

# Phase 5 Plan 2: Template API Handlers Summary

**HTTP handlers and routes for template CRUD, item reorder, and budget-from-template generation wired to the query layer built in Plan 01**

## Performance

- **Duration:** ~1 min
- **Started:** 2026-03-12T11:09:32Z
- **Completed:** 2026-03-12T11:10:40Z
- **Tasks:** 2
- **Files modified:** 2

## Accomplishments

- All 7 template handler methods added to handlers.go: GetTemplate, UpdateTemplateName, CreateTemplateItem, UpdateTemplateItem, DeleteTemplateItem, ReorderTemplateItems, GenerateBudget
- Handler-level validation for template items: one_off tier rejected with 400, fixed tier requires budgeted_amount
- GenerateBudget uses errors.As to detect BudgetExistsError and returns structured 409 with budget_id
- /api/template route group fully wired in router.go with correct static-before-param ordering for /items/reorder vs /items/{itemId}
- POST /api/budgets/generate placed before /{id} routes to avoid "generate" being parsed as a budget ID
- Full backend builds and vets clean

## Task Commits

Each task committed atomically:

1. **Task 1: Template handlers and budget generation handler** - `ceca2fc` (feat)
2. **Task 2: Wire routes in router.go** - `387507b` (feat)

## Files Created/Modified

- `backend/internal/api/handlers.go` - Added 7 new handler methods, added `errors` import
- `backend/internal/api/router.go` - Added /api/template route group and POST /api/budgets/generate

## Decisions Made

- `PUT /items/reorder` registered before `PUT /items/{itemId}` — chi matches static routes first when registered in order; this prevents "reorder" being treated as an itemId parameter
- `GenerateBudget` returns JSON body `{"error": "budget already exists", "budget_id": "..."}` on 409 — uses `BudgetExistsError.ExistingBudgetID` (field name established in Plan 01)
- `UpdateTemplateName` handler returns 404 for any error — since lazy creation means the only failure mode before an item exists is "no template", and connection errors are rare; consistent with UpdateCategory pattern

## Deviations from Plan

None - plan executed exactly as written. The budget item handler updates (item_tier pass-through) were already done in Plan 01's auto-fix, so Task 1 focused entirely on new template handlers.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required. Routes are live after next server start.

## Next Phase Readiness

- All REST endpoints for Phase 6 (template UI) are available
- API contract is stable: GET returns empty items array (not error) when no template exists
- 409 conflict response includes budget_id so frontend can navigate to existing budget

## Self-Check: PASSED

Both modified files verified on disk. Both task commits (ceca2fc, 387507b) present in git log. `go build ./...` and `go vet ./...` pass clean.

---
*Phase: 05-template-data-model-and-api*
*Completed: 2026-03-12*