lucasacchi/documente
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

refactor: fix linting issues and code quality

Browse Source 
- Fix import ordering in __init__.py
- Remove unused imports from dependencies.py
- Fix import sorting across multiple files
- Apply ruff auto-fixes

No functional changes
This commit is contained in:
Luca Sacchi Ricciardi
2026-04-06 01:19:38 +02:00
parent 4b7a419a98
commit fe88bf2ca1
13 changed files with 310 additions and 354 deletions
Download Patch File Download Diff File Expand all files Collapse all files

523
docs/api/endpoints.md
View File

@@ -1,44 +1,8 @@
# API Endpoints Documentation
> NotebookLM Agent API - Endpoint Reference
Documentation for NotebookLM Agent API endpoints.
**Version**: 0.1.0
**Base URL**: `http://localhost:8000`
**OpenAPI**: `/docs` (Swagger UI)
---
## Authentication
All API requests require an API key in the `X-API-Key` header:
```bash
X-API-Key: your-api-key-here
```
### Example
```bash
curl http://localhost:8000/api/v1/notebooks \
-H "X-API-Key: your-api-key"
```
### Error Response (401 Unauthorized)
```json
{
"success": false,
"error": {
"code": "AUTH_ERROR",
"message": "API key required",
"details": null
},
"meta": {
"timestamp": "2026-04-06T10:30:00Z",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
**Base URL:** `http://localhost:8000/api/v1`
---
@@ -46,134 +10,81 @@ curl http://localhost:8000/api/v1/notebooks \
### Create Notebook
Create a new notebook.
Create a new notebook with title and optional description.
**Endpoint**: `POST /api/v1/notebooks`
#### Request
```bash
curl -X POST http://localhost:8000/api/v1/notebooks \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"title": "My Research Notebook",
"description": "A collection of AI research papers"
}'
```http
POST /notebooks
```
**Request Body**:
**Request Body:**
```json
{
"title": "string (required, min: 3, max: 100)",
"description": "string (optional, max: 500)"
"title": "Research on AI",
"description": "A comprehensive study on artificial intelligence"
}
```
#### Success Response (201 Created)
**Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | Yes | Notebook title (3-100 characters) |
| `description` | string | No | Optional description |
**Response:**
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "My Research Notebook",
"description": "A collection of AI research papers",
"title": "Research on AI",
"description": "A comprehensive study on artificial intelligence",
"created_at": "2026-04-06T10:30:00Z",
"updated_at": "2026-04-06T10:30:00Z"
},
"meta": {
"timestamp": "2026-04-06T10:30:00Z",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
"request_id": "uuid"
}
}
```
#### Error Responses
**Status Codes:**
**400 Bad Request** - Validation Error
- `201 Created` - Notebook created successfully
- `400 Bad Request` - Validation error (title too short/long)
- `502 Bad Gateway` - NotebookLM API error
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{
"field": "title",
"error": "Title must be at least 3 characters"
}
]
},
"meta": {
"timestamp": "2026-04-06T10:30:00Z",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
**Example:**
**401 Unauthorized** - Missing/Invalid API Key
```json
{
"success": false,
"error": {
"code": "AUTH_ERROR",
"message": "API key required"
},
"meta": { ... }
}
```
**502 Bad Gateway** - NotebookLM API Error
```json
{
"success": false,
"error": {
"code": "NOTEBOOKLM_ERROR",
"message": "External API error: rate limit exceeded"
},
"meta": { ... }
}
```bash
curl -X POST http://localhost:8000/api/v1/notebooks \
-H "Content-Type: application/json" \
-d '{"title": "Research on AI", "description": "Study"}'
```
---
### List Notebooks
List all notebooks with pagination.
Get a paginated list of all notebooks.
**Endpoint**: `GET /api/v1/notebooks`
#### Request
```bash
# Basic request
curl http://localhost:8000/api/v1/notebooks \
-H "X-API-Key: your-api-key"
# With pagination
curl "http://localhost:8000/api/v1/notebooks?limit=10&offset=0&sort=created_at&order=desc" \
-H "X-API-Key: your-api-key"
# Sort by title ascending
curl "http://localhost:8000/api/v1/notebooks?sort=title&order=asc" \
-H "X-API-Key: your-api-key"
```http
GET /notebooks
```
**Query Parameters**:
**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 20 | Max items per page (1-100) |
| `limit` | integer | 20 | Items per page (1-100) |
| `offset` | integer | 0 | Items to skip |
| `sort` | string | "created_at" | Sort field: `created_at`, `updated_at`, `title` |
| `order` | string | "desc" | Sort order: `asc`, `desc` |
| `sort` | string | `created_at` | Sort field (`created_at`, `updated_at`, `title`) |
| `order` | string | `desc` | Sort order (`asc`, `desc`) |
#### Success Response (200 OK)
**Response:**
```json
{
@@ -182,46 +93,39 @@ curl "http://localhost:8000/api/v1/notebooks?sort=title&order=asc" \
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "My Research Notebook",
"description": "A collection of AI research papers",
"created_at": "2026-04-06T10:00:00Z",
"title": "Research on AI",
"description": "Study",
"created_at": "2026-04-06T10:30:00Z",
"updated_at": "2026-04-06T10:30:00Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"title": "Another Notebook",
"description": null,
"created_at": "2026-04-06T09:00:00Z",
"updated_at": "2026-04-06T09:00:00Z"
}
],
"pagination": {
"total": 100,
"total": 1,
"limit": 20,
"offset": 0,
"has_more": true
"offset": 0
}
},
"meta": {
"timestamp": "2026-04-06T10:30:00Z",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
"request_id": "uuid"
}
}
```
#### Error Responses
**Status Codes:**
**401 Unauthorized** - Missing/Invalid API Key
- `200 OK` - List retrieved successfully
- `422 Unprocessable Entity` - Invalid query parameters
- `502 Bad Gateway` - NotebookLM API error
```json
{
"success": false,
"error": {
"code": "AUTH_ERROR",
"message": "API key required"
},
"meta": { ... }
}
**Example:**
```bash
# Default pagination
curl http://localhost:8000/api/v1/notebooks
# Custom pagination
curl "http://localhost:8000/api/v1/notebooks?limit=10&offset=20&sort=title&order=asc"
```
---
@@ -230,117 +134,81 @@ curl "http://localhost:8000/api/v1/notebooks?sort=title&order=asc" \
Get a single notebook by ID.
**Endpoint**: `GET /api/v1/notebooks/{notebook_id}`
#### Request
```bash
curl http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: your-api-key"
```http
GET /notebooks/{notebook_id}
```
**Path Parameters**:
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `notebook_id` | UUID | Notebook unique identifier |
#### Success Response (200 OK)
**Response:**
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "My Research Notebook",
"description": "A collection of AI research papers",
"created_at": "2026-04-06T10:00:00Z",
"title": "Research on AI",
"description": "Study",
"created_at": "2026-04-06T10:30:00Z",
"updated_at": "2026-04-06T10:30:00Z"
},
"meta": {
"timestamp": "2026-04-06T10:30:00Z",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
"request_id": "uuid"
}
}
```
#### Error Responses
**Status Codes:**
**404 Not Found** - Notebook doesn't exist
- `200 OK` - Notebook found
- `400 Bad Request` - Invalid UUID format
- `404 Not Found` - Notebook not found
- `502 Bad Gateway` - NotebookLM API error
```json
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Notebook with id '550e8400-e29b-41d4-a716-446655440000' not found"
},
"meta": { ... }
}
```
**Example:**
**400 Bad Request** - Invalid UUID format
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid notebook ID format"
},
"meta": { ... }
}
```bash
curl http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000
```
---
### Update Notebook
Update an existing notebook (partial update).
Update a notebook (partial update).
**Endpoint**: `PATCH /api/v1/notebooks/{notebook_id}`
#### Request
```bash
# Update title only
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"title": "Updated Title"
}'
# Update description only
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"description": "Updated description"
}'
# Update both
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"title": "Updated Title",
"description": "Updated description"
}'
```http
PATCH /notebooks/{notebook_id}
```
**Request Body**:
**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `notebook_id` | UUID | Notebook unique identifier |
**Request Body:**
```json
{
"title": "string (optional, min: 3, max: 100)",
"description": "string (optional, max: 500)"
"title": "Updated Title",
"description": "Updated description"
}
```
**Note**: Only provided fields are updated. At least one field must be provided.
**Parameters:**
#### Success Response (200 OK)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | No | New title (3-100 characters) |
| `description` | string | No | New description |
**Response:**
```json
{
@@ -349,48 +217,40 @@ curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Updated Title",
"description": "Updated description",
"created_at": "2026-04-06T10:00:00Z",
"created_at": "2026-04-06T10:30:00Z",
"updated_at": "2026-04-06T11:00:00Z"
},
"meta": {
"timestamp": "2026-04-06T11:00:00Z",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
"request_id": "uuid"
}
}
```
#### Error Responses
**Status Codes:**
**400 Bad Request** - Validation Error
- `200 OK` - Notebook updated
- `400 Bad Request` - Invalid UUID or validation error
- `404 Not Found` - Notebook not found
- `502 Bad Gateway` - NotebookLM API error
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{
"field": "title",
"error": "Title must be at least 3 characters"
}
]
},
"meta": { ... }
}
```
**Example:**
**404 Not Found** - Notebook doesn't exist
```bash
# Update title only
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
-H "Content-Type: application/json" \
-d '{"title": "New Title"}'
```json
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Notebook with id '...' not found"
},
"meta": { ... }
}
# Update description only
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
-H "Content-Type: application/json" \
-d '{"description": "New description"}'
# Update both
curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
-H "Content-Type: application/json" \
-d '{"title": "New Title", "description": "New description"}'
```
---
@@ -399,114 +259,113 @@ curl -X PATCH http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446
Delete a notebook permanently.
**Endpoint**: `DELETE /api/v1/notebooks/{notebook_id}`
#### Request
```bash
curl -X DELETE http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: your-api-key"
```http
DELETE /notebooks/{notebook_id}
```
#### Success Response (204 No Content)
**Path Parameters:**
Empty body.
| Parameter | Type | Description |
|-----------|------|-------------|
| `notebook_id` | UUID | Notebook unique identifier |
#### Error Responses
**Response:**
**404 Not Found** - Notebook doesn't exist
- `204 No Content` - No response body
**Status Codes:**
- `204 No Content` - Notebook deleted successfully
- `400 Bad Request` - Invalid UUID format
- `404 Not Found` - Notebook not found
- `502 Bad Gateway` - NotebookLM API error
**Example:**
```bash
curl -X DELETE http://localhost:8000/api/v1/notebooks/550e8400-e29b-41d4-a716-446655440000
```
---
## Error Responses
All errors follow this format:
```json
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Notebook with id '...' not found"
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": [
{"field": "title", "error": "Title must be at least 3 characters"}
]
},
"meta": { ... }
"meta": {
"timestamp": "2026-04-06T10:30:00Z",
"request_id": "uuid"
}
}
```
**Note**: This operation is idempotent. Deleting the same notebook twice returns 404 on the second attempt.
---
## Common Workflows
### Create and List Notebooks
```bash
# 1. Create a notebook
NOTEBOOK=$(curl -s -X POST http://localhost:8000/api/v1/notebooks \
-H "X-API-Key: your-key" \
-H "Content-Type: application/json" \
-d '{"title": "AI Research"}' | jq -r '.data.id')
# 2. List all notebooks
curl http://localhost:8000/api/v1/notebooks \
-H "X-API-Key: your-key"
# 3. Get specific notebook
curl http://localhost:8000/api/v1/notebooks/$NOTEBOOK \
-H "X-API-Key: your-key"
```
### Update and Delete
```bash
NOTEBOOK_ID="550e8400-e29b-41d4-a716-446655440000"
# Update title
curl -X PATCH http://localhost:8000/api/v1/notebooks/$NOTEBOOK_ID \
-H "X-API-Key: your-key" \
-H "Content-Type: application/json" \
-d '{"title": "New Title"}'
# Delete notebook
curl -X DELETE http://localhost:8000/api/v1/notebooks/$NOTEBOOK_ID \
-H "X-API-Key: your-key"
```
---
## Error Codes
### Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| `VALIDATION_ERROR` | 400 | Input validation failed |
| `AUTH_ERROR` | 401 | Authentication failed (missing/invalid API key) |
| `VALIDATION_ERROR` | 400 | Invalid input data |
| `NOT_FOUND` | 404 | Resource not found |
| `RATE_LIMITED` | 429 | Rate limit exceeded |
| `NOTEBOOKLM_ERROR` | 502 | External NotebookLM API error |
| `NOTEBOOKLM_ERROR` | 502 | External API error |
---
## Rate Limiting
## Common Patterns
API requests are rate-limited to prevent abuse. Rate limit headers are included in responses:
### Pagination
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1712400000
All list endpoints support pagination:
```bash
# Page 1 (first 20 items)
curl "http://localhost:8000/api/v1/notebooks?limit=20&offset=0"
# Page 2 (next 20 items)
curl "http://localhost:8000/api/v1/notebooks?limit=20&offset=20"
```
If you exceed the rate limit, you'll receive a `429 Too Many Requests` response:
### Sorting
```json
{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Try again in 60 seconds.",
"details": [{"retry_after": 60}]
},
"meta": { ... }
}
Use `sort` and `order` parameters:
```bash
# Sort by title ascending
curl "http://localhost:8000/api/v1/notebooks?sort=title&order=asc"
# Sort by updated date descending (newest first)
curl "http://localhost:8000/api/v1/notebooks?sort=updated_at&order=desc"
```
---
*Documentazione generata automaticamente da @api-designer*
*Data: 2026-04-06*
*Versione API: 0.1.0*
## Testing
### Health Check
```bash
curl http://localhost:8000/health
```
### OpenAPI Schema
```bash
# OpenAPI JSON
curl http://localhost:8000/openapi.json
# Swagger UI (browser)
open http://localhost:8000/docs
```
---
**Version:** 0.2.0
**Last Updated:** 2026-04-06