hamid
37 lines
1.2 KiB
Markdown
37 lines
1.2 KiB
Markdown
# Contract — <Domain> (backend phase bN)
|
|
|
|
> One-line: what this domain's API covers. Assumes
|
|
> [`../conventions/api-conventions.md`](../conventions/api-conventions.md) +
|
|
> [`../conventions/money-and-types.md`](../conventions/money-and-types.md). Source of truth for the
|
|
> machine schema: [`../openapi/`](../openapi/README.md).
|
|
|
|
**Status:** live as of backend-phase-bN · **Frontend consumer:** frontend-phase-fM
|
|
|
|
## Enums used
|
|
- `<enum_name>`: `value_a` | `value_b` | … — meaning of each.
|
|
|
|
## Endpoints
|
|
|
|
### `<HTTP> api/v1/<controller>/<action>`
|
|
- **Purpose:** …
|
|
- **Auth:** none | authenticated | policy/role … · **Rate-limited:** yes/no · **Idempotency key:** yes/no
|
|
- **Path/query params:** `name` (type) — meaning; pagination `page`/`page_size` (default/max) for lists.
|
|
- **Request body:**
|
|
```json
|
|
{ "field": "example" }
|
|
```
|
|
- **Success `200` payload (`data`):**
|
|
```json
|
|
{ "field": "example" }
|
|
```
|
|
- **Failure cases:** `400` …, `401` …, `403` …, `404` …, `409` … (when/why each).
|
|
- **Notes:** masking, two-stage disclosure, tenancy, side effects (notifications/ledger/audit), etc.
|
|
|
|
_(repeat per endpoint)_
|
|
|
|
## Shared shapes
|
|
- `<DtoName>`: field-by-field (name, type, nullable, masked?, meaning).
|
|
|
|
## Changelog
|
|
- bN — initial contract.
|