32 lines
1.3 KiB
Markdown
32 lines
1.3 KiB
Markdown
# Advisory Gateway Contract (draft v0.1)
|
|
|
|
Scope: proxy Advisory surfaces through the Web gateway with tenant scoping, deterministic responses, ETag caching, and offline-friendly pagination.
|
|
|
|
## Security / headers
|
|
- `Authorization: Bearer <token>` (or `DPoP` where configured)
|
|
- `X-Stella-Tenant: <tenantId>` (required; see `docs/api/gateway/tenant-auth.md`)
|
|
- `X-Stella-Project: <projectId>` (optional)
|
|
- `X-Stella-Trace-Id: <traceId>` (optional; clients SHOULD send one)
|
|
- Scopes: `advisory:read`
|
|
|
|
## Endpoints
|
|
- `GET /advisories` — list advisories (tenant-scoped).
|
|
- Query params: `search`, `severity`, `sortBy`, `sortOrder`, `limit`, `continuationToken`
|
|
- Response: `AdvisoryListResponse` (see sample)
|
|
- `GET /advisories/{advisoryId}` — advisory detail (tenant-scoped).
|
|
|
|
## Caching & pagination
|
|
- `limit` max: `200`.
|
|
- Cursor/paging uses `continuationToken` (opaque string).
|
|
- `ETag` MUST be a stable hash over a sorted payload; clients MAY send `If-None-Match`.
|
|
- Recommended headers: `Cache-Control: private, max-age=60, stale-if-error=300`.
|
|
|
|
## Determinism rules
|
|
- Ordering: `items` sorted by `(advisoryId asc)` unless `sortBy` is supplied; ties break by `advisoryId`.
|
|
- Timestamps: ISO-8601 UTC.
|
|
|
|
## Samples
|
|
- `docs/api/gateway/samples/advisories-list.json`
|
|
- `docs/api/gateway/samples/advisory-detail.json`
|
|
|