Adrien
69 lines
1.7 KiB
Markdown
69 lines
1.7 KiB
Markdown
# API Contract: Topics — Summary Persistence
|
|
|
|
**Base path**: `/api/v1/topics`
|
|
|
|
---
|
|
|
|
## Existing endpoint (unchanged behaviour, extended response)
|
|
|
|
### `POST /api/v1/topics/{id}/summary`
|
|
|
|
Generates a new summary for the topic, **persists it**, and returns it.
|
|
|
|
**Path param**: `id` — topic id (e.g. `intracranial-aneurysms`)
|
|
|
|
**Response** `200 OK`:
|
|
```json
|
|
{
|
|
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
|
|
"summaryNumber": 3,
|
|
"topicId": "intracranial-aneurysms",
|
|
"topicName": "Intracranial Aneurysms",
|
|
"summary": "## Key Points\n...",
|
|
"sources": [
|
|
{ "bookId": "uuid", "bookTitle": "Youmans & Winn", "page": 142 }
|
|
],
|
|
"generatedAt": "2026-04-07T10:23:00Z"
|
|
}
|
|
```
|
|
|
|
**Error responses**:
|
|
- `404 Not Found` — topic id does not exist
|
|
- `503 Service Unavailable` — no books ready (existing `NoKnowledgeSourceException`)
|
|
|
|
---
|
|
|
|
## New endpoints
|
|
|
|
### `GET /api/v1/topics/{id}/summaries`
|
|
|
|
Returns the list of saved summaries for a topic (no full text — list metadata only).
|
|
|
|
**Path param**: `id` — topic id
|
|
|
|
**Response** `200 OK`:
|
|
```json
|
|
[
|
|
{ "id": "uuid-1", "summaryNumber": 1, "generatedAt": "2026-04-06T08:00:00Z" },
|
|
{ "id": "uuid-2", "summaryNumber": 2, "generatedAt": "2026-04-06T09:15:00Z" }
|
|
]
|
|
```
|
|
|
|
Ordered ascending by `summaryNumber`. Empty array if no summaries saved yet.
|
|
|
|
**Error responses**:
|
|
- `404 Not Found` — topic id does not exist
|
|
|
|
---
|
|
|
|
### `GET /api/v1/topics/{id}/summaries/{summaryId}`
|
|
|
|
Fetches the full content of a specific saved summary.
|
|
|
|
**Path params**: `id` — topic id, `summaryId` — summary UUID
|
|
|
|
**Response** `200 OK`: same shape as `POST /summary` response above.
|
|
|
|
**Error responses**:
|
|
- `404 Not Found` — topic or summary not found
|