27 خطوط
989 B
Markdown
27 خطوط
989 B
Markdown
# API Guidelines
|
|
|
|
- Base path: `/api/v1`
|
|
- JSON request and response bodies
|
|
- Resource identifiers are opaque strings
|
|
- ISO 8601 UTC timestamps at boundaries
|
|
- Locale and timezone are explicit request context
|
|
- Cursor pagination for high-volume feeds; page pagination where users need page counts
|
|
- Filter and sort fields are allow-listed
|
|
- Mutations support idempotency keys where duplicate execution is costly
|
|
|
|
## Response envelope
|
|
|
|
```json
|
|
{
|
|
"data": {},
|
|
"meta": { "requestId": "..." }
|
|
}
|
|
```
|
|
|
|
Validation errors use a stable machine code, localized user-safe message, and field errors. Authorization must not leak cross-tenant existence. Controllers delegate to application commands and queries.
|
|
|
|
## Taxonomy endpoints
|
|
|
|
`taxonomy-types`, `taxonomy-nodes`, `taxonomy-relationships`, `content-mappings`, `mapping-suggestions`, `evidence`, `capabilities`, `capability-snapshots`, `skill-expectations`, `skill-gaps`, and `content-coverage` live under `/api/v1` and are policy protected.
|
|
|