Add API to repo
This commit is contained in:
1 parent
f80792d739
commit
52d087ce90
20 files changed
+2592
No files matched your search
@@ -0,0 +1,117 @@
|
||||
# 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._
|
||||
Reference in new issue
Block a user