79 lines
1.4 KiB
Markdown
79 lines
1.4 KiB
Markdown
# API Data Flow (Strict)
|
|
|
|
This document defines the **apps/api** data flow and responsibilities.
|
|
|
|
API scope:
|
|
|
|
- `apps/api/**`
|
|
|
|
## 1) API role
|
|
|
|
The API is a **delivery application**.
|
|
|
|
Responsibilities:
|
|
|
|
- HTTP transport boundary
|
|
- authentication and authorization enforcement
|
|
- request validation (transport shape)
|
|
- mapping between HTTP DTOs and Core inputs
|
|
- calling Core use cases
|
|
- mapping Core results into HTTP responses
|
|
|
|
## 2) API data types (strict)
|
|
|
|
### 2.1 Request DTO
|
|
|
|
Definition: HTTP request contract shape.
|
|
|
|
Rules:
|
|
|
|
- lives in the API layer
|
|
- validated at the API boundary
|
|
- never enters Core unchanged
|
|
|
|
### 2.2 Response DTO
|
|
|
|
Definition: HTTP response contract shape.
|
|
|
|
Rules:
|
|
|
|
- lives in the API layer
|
|
- never contains domain objects
|
|
|
|
### 2.3 API Presenter
|
|
|
|
Definition: mapping logic from Core results to HTTP response DTOs.
|
|
|
|
Rules:
|
|
|
|
- pure transformation
|
|
- no business rules
|
|
- may hold state per request
|
|
|
|
## 3) Canonical flow
|
|
|
|
```text
|
|
HTTP Request
|
|
↓
|
|
Guards (auth, authorization, feature availability)
|
|
↓
|
|
Controller (transport-only)
|
|
↓
|
|
Mapping: Request DTO → Core input
|
|
↓
|
|
Core Use Case
|
|
↓
|
|
Mapping: Core result → Response DTO (Presenter)
|
|
↓
|
|
HTTP Response
|
|
```
|
|
|
|
## 4) Non-negotiable rules
|
|
|
|
1. Controllers contain no business rules.
|
|
2. Controllers do not construct domain objects.
|
|
3. Core results never leave the API without mapping.
|
|
|
|
See authorization model: [`docs/architecture/api/AUTHORIZATION.md`](docs/architecture/api/AUTHORIZATION.md:1).
|
|
|