118 lines
3.4 KiB
Markdown
118 lines
3.4 KiB
Markdown
# Atlas Librarian API Specification (v0.1.0)
|
|
|
|
This document outlines the endpoints provided by the Atlas Librarian API Gateway.
|
|
|
|
**Base URL:** `/v1`
|
|
|
|
## Authentication
|
|
|
|
Currently, no authentication is required.
|
|
|
|
## Tasks
|
|
|
|
Long-running operations like crawling and downloading are handled via background tasks. You initiate a task via a POST request and then poll the status endpoint using the returned `task_id`.
|
|
|
|
### Task Object (`TaskInfo`)
|
|
|
|
```json
|
|
{
|
|
"task_id": "string (uuid)",
|
|
"name": "string | null (e.g., 'crawl', 'download')",
|
|
"state": "string (queued | running | success | error)",
|
|
"progress": "number | null (0.0 to 1.0, only present while running)",
|
|
"detail": "string | null (details about state, especially errors)",
|
|
"download_links": "array[string] | null (only for successful download tasks)"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Endpoints
|
|
|
|
### Crawler
|
|
|
|
**Tags:** `Crawler`
|
|
|
|
- **`POST /v1/crawl`**
|
|
- **Summary:** Start Course Crawl
|
|
- **Description:** Initiates a background task to crawl Moodle course information. `no_cache=true` forces a fresh crawl.
|
|
- **Request Body:** `CrawlRequest`
|
|
|
|
```json
|
|
{
|
|
"no_cache": "boolean (optional, default: false)"
|
|
}
|
|
```
|
|
|
|
- **Response (202 Accepted):** `TaskInfo` (initial state: queued)
|
|
- **`GET /v1/crawl/status/{task_id}`**
|
|
- **Summary:** Get Crawl Task Status
|
|
- **Description:** Retrieves the current status (queued, running, success, error) and progress of a specific crawl task.
|
|
- **Path Parameter:** `task_id` (string)
|
|
- **Response (200 OK):** `TaskInfo`
|
|
- **Response (404 Not Found):** If `task_id` does not exist.
|
|
|
|
### Downloader
|
|
|
|
**Tags:** `Downloader`
|
|
|
|
- **`POST /v1/download`**
|
|
- **Summary:** Start Course Material Download
|
|
- **Description:** Initiates a background task to download materials for the specified list of courses.
|
|
- **Request Body:** `DownloadRequest`
|
|
|
|
```json
|
|
{
|
|
"courses": [
|
|
{
|
|
"module_id": "string",
|
|
"term_id": "string"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
- **Response (202 Accepted):** `TaskInfo` (initial state: queued)
|
|
- **Response (400 Bad Request):** If `courses` list is empty.
|
|
- **`GET /v1/download/status/{task_id}`**
|
|
- **Summary:** Get Download Task Status
|
|
- **Description:** Retrieves the current status (queued, running, success, error) and progress of a specific download task. Includes `download_links` on success.
|
|
- **Path Parameter:** `task_id` (string)
|
|
- **Response (200 OK):** `TaskInfo`
|
|
- **Response (404 Not Found):** If `task_id` does not exist.
|
|
|
|
### Metadata
|
|
|
|
**Tags:** `Metadata`
|
|
|
|
- **`GET /v1/terms`**
|
|
- **Summary:** Get All Terms
|
|
- **Description:** Retrieves a list of all available academic terms (e.g., 'HS24', 'FS25').
|
|
- **Response (200 OK):** `List[string]`
|
|
|
|
```json
|
|
["HS24", "FS25"]
|
|
```
|
|
|
|
### Summaries
|
|
|
|
**Tags:** `Summaries`
|
|
|
|
- **`GET /v1/summaries/{term_id}/{course_id}`**
|
|
- **Summary:** Get Course Summary
|
|
- **Description:** Retrieves the generated summary content (in Markdown format) for a specific course within a specific term.
|
|
- **Path Parameters:** `term_id` (string), `course_id` (string)
|
|
- **Response (200 OK):** `SummaryResponse`
|
|
|
|
```json
|
|
{
|
|
"summary": "string (Markdown)"
|
|
}
|
|
```
|
|
|
|
- **Response (404 Not Found):** If the summary for the given course/term does not exist.
|
|
|
|
---
|
|
|
|
_Generated based on FastAPI application structure._
|