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
This commit is contained in:
58
openspec/changes/api-resource-standard/proposal.md
Normal file
58
openspec/changes/api-resource-standard/proposal.md
Normal file
@@ -0,0 +1,58 @@
|
||||
## 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:
|
||||
|
||||
1. **Inconsistent Response Format**: Some endpoints return arrays, others objects, making client-side parsing error-prone
|
||||
2. **No Future-Proofing**: Adding metadata (pagination, relationships, meta) requires breaking changes later
|
||||
3. **Missing Data Wrapper**: Architecture requires `"data"` key for all responses to support future transformations
|
||||
4. **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
|
||||
Reference in New Issue
Block a user