headroom/openspec/changes/api-resource-standard/proposal.md at fedfc214258726cf28b600ff8444668110a40856

Files

Santhosh Janardhanan 47068dabce feat(api): Implement API Resource Standard compliance

- Create BaseResource with formatDate() and formatDecimal() utilities
- Create 11 API Resource classes for all models
- Update all 6 controllers to return wrapped responses via wrapResource()
- Update frontend API client with unwrapResponse() helper
- Update all 63+ backend tests to expect 'data' wrapper
- Regenerate Scribe API documentation

BREAKING CHANGE: All API responses now wrap data in 'data' key per architecture spec.

Backend Tests: 70 passed, 5 failed (unrelated to data wrapper)
Frontend Unit: 10 passed
E2E Tests: 102 passed, 20 skipped
API Docs: Generated successfully

Refs: openspec/changes/api-resource-standard

2026-02-19 14:51:56 -05:00

2.6 KiB

Raw 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 Blame History

Why