frontend-angular-api-service

# Angular API Service Development Workflow

Use when creating/modifying API services extending PlatformApiService for backend communication.

## Decision Tree

```
What kind of API service?
├── Standard CRUD            → extend PlatformApiService + get/post/put/deleteRequest
├── With caching             → + enableCache option in get() calls
├── File upload/download     → + postFormData() / getBlob()
├── External API             → + override getDefaultHeaders()
├── Search/autocomplete      → + debounce in component, cache short-lived
└── Validation endpoint      → return Observable<boolean>
```

## Workflow

1. **Search** existing services: `grep "{Feature}ApiService" --include="*.ts"`
2. **Read** references (see Read Directives below)
3. **Define** DTOs: request interfaces, response interfaces, command interfaces
4. **Create** service extending `PlatformApiService` with `@Injectable({ providedIn: 'root' })`
5. **Implement** `apiUrl` getter using `environment.apiUrl + '/api/{Controller}'`
6. **Add** query methods (get), command methods (post/put/delete), validation methods
7. **Verify** checklist below

## Key Rules

- Always extend `PlatformApiService` (never use `HttpClient` directly)
- Use `environment.apiUrl` for base URL (never hardcode)
- All methods must have return type annotations: `Observable<T>`
- Define DTOs for all request/response types
- Use `{ enableCache: true, cacheKey, cacheDurationMs }` for cacheable endpoints
- File uploads use `postFormData()`, downloads use `getBlob()`
- Error handling done in component via `tapResponse()`, not in service

## File Location

```
src/Frontend/libs/apps-domains/src/lib/{domain}/services/{feature}-api.service.ts
```

## ⚠️ MUST READ Before Implementation

**IMPORTANT: You MUST read these files before writing any code. Do NOT skip.**

1. **⚠️ MUST READ** `.claude/skills/shared/angular-design-system.md` — platform-core imports
2. **⚠️ MUST READ** `.claude/skills/frontend-angular-api-service/references/api-service-patterns.md` — CRUD, caching, upload, search patterns
3. **⚠️ MUST READ** target app design system: `docs/design-system/07-technical-guide.md`

## Anti-Patterns

- `constructor(private http: HttpClient)` - must extend `PlatformApiService`
- Hardcoded URLs: `this.get('https://api.example.com/...')` - use `environment`
- Missing return type: `getUser(id)` - must be `getUser(id): Observable<UserDto>`
- Untyped response: `this.get('/users')` - must be `this.get<UserDto[]>('/users')`
- Error handling in service - let component handle via `tapResponse()`

## Verification Checklist

- [ ] Extends `PlatformApiService`
- [ ] `apiUrl` getter returns `environment.apiUrl + '/api/{Controller}'`
- [ ] All methods have `Observable<T>` return type
- [ ] DTOs defined for request/response types
- [ ] Caching configured for stable lookup endpoints
- [ ] File operations use `postFormData`/`getBlob`
- [ ] `@Injectable({ providedIn: 'root' })` decorator


## IMPORTANT Task Planning Notes

- Always plan and break many small todo tasks
- Always add a final review todo task to review the works done at the end to find any fix or enhancement needed