headroom/openspec/changes/archive/2026-03-08-api-resource-standard/proposal.md at tdd-headroom

Files

Santhosh Janardhanan b8262bbcaf docs(openspec): archive completed changes and sync main specs

Archive three completed changes to archive/:
- api-resource-standard (70 tasks, 14 resource classes)
- capacity-expert-mode (68 tasks, expert mode planning grid)
- enhanced-allocation (62 tasks, planning fidelity + reporting)

Sync all delta specs to main specs/:
- api-resource-standard: API response standardization
- capacity-expert-mode: Expert mode toggle, grid, KPIs, batch API
- resource-allocation: Month execution comparison, bulk, untracked
- untracked-allocation: Null team member support
- allocation-indicators: Variance indicators (red/amber/neutral)
- monthly-budget: Explicit project-month planning

All changes verified and tested (157 tests passing).

2026-03-08 19:13:28 -04:00

2.6 KiB

Raw Permalink Blame History

Why

The Headroom API currently returns raw JSON responses without a standardized wrapper. This violates the architecture specification (docs/headroom-architecture.md, lines 315-393) which mandates Laravel API Resources for consistent JSON structure. This technical debt creates several problems:

Inconsistent Response Format: Some endpoints return arrays, others objects, making client-side parsing error-prone
No Future-Proofing: Adding metadata (pagination, relationships, meta) requires breaking changes later
Missing Data Wrapper: Architecture requires "data" key for all responses to support future transformations
No Resource Abstraction: Direct model exposure limits ability to transform data without breaking clients

Since the application is pre-production and not in active use, we should fix this now to avoid permanent technical debt.

What Changes

Breaking Changes

BREAKING: All API responses will be wrapped in "data" key
BREAKING: Collections will use Laravel's resource collection format with "data" array
BREAKING: Frontend API client must unwrap response.data instead of direct access

New Components

Create app/Http/Resources/ directory structure
Create 11 API Resource classes for consistent transformation
Create base BaseResource with common formatting utilities

Updated Components

Update 6 controllers to use API Resources instead of response()->json()
Update 63 backend tests to expect "data" wrapper in responses
Update frontend API client to handle new response format
Regenerate Scribe API documentation

Capabilities

New Capabilities

api-resource-standard: Standardize all API responses using Laravel API Resources with consistent "data" wrapper

Modified Capabilities

(none - this is a refactoring change, no functional requirements change)

Impact

Backend (Laravel)

Files Created: 11 new resource classes in app/Http/Resources/
Files Modified: 6 controllers in app/Http/Controllers/Api/
Tests Updated: 63 feature tests
New Tests: 11+ unit tests for resource classes

Frontend (SvelteKit)

Files Modified: API client in src/lib/api/ directory
Breaking: All API calls must access response.json().data instead of response.json()

Documentation

Regenerated: Scribe API docs will show new response format

Dependencies

No new dependencies required (Laravel's built-in API Resources)

Performance

Minimal impact - API Resources add negligible overhead
Slight improvement: Consistent caching keys can be optimized

2.6 KiB Raw Permalink Blame History

Why