Nicolas Cantu
088eab84b7
- Add ia_dev submodule (projects/smart_ide on forge 4nk) - Document APIs, orchestrator, gateway, local-office, rollout - Add systemd/scripts layout; relocate setup scripts - Remove obsolete nginx/enso-only docs from this repo scope
116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
# API — local-office
|
||
|
||
Service FastAPI : gestion de fichiers Office (upload, liste, métadonnées, téléchargement, commandes sur **docx**, suppression). Auth par **clé API**, pas Bearer.
|
||
|
||
- **Code** : [`services/local-office/`](../../services/local-office/)
|
||
- **Doc fonctionnelle** : [features/local-office.md](../features/local-office.md)
|
||
- **OpenAPI** : `GET http://<host>:<port>/docs` (ex. port `8000` en run local)
|
||
|
||
## Authentification
|
||
|
||
Toutes les routes documentées ici exigent :
|
||
|
||
```http
|
||
X-API-Key: <une des clés listées dans API_KEYS>
|
||
```
|
||
|
||
Les clés sont définies côté serveur (variable `API_KEYS`, liste séparée par virgules). Chaque document est associé à la clé qui l’a créé ; accès aux ressources d’un autre propriétaire renvoie **404**.
|
||
|
||
**Rate limiting** : requêtes limitées par clé (slowapi, voir `RATE_LIMIT_PER_MINUTE`).
|
||
|
||
## Préfixe des routes
|
||
|
||
Le routeur est monté sous **`/documents`** (pas de préfixe `/api`).
|
||
|
||
## Endpoints
|
||
|
||
### `POST /documents`
|
||
|
||
Upload **multipart** d’un fichier Office.
|
||
|
||
- **En-têtes** : `X-API-Key` ; pour la partie fichier, `Content-Type` doit être l’un des types autorisés :
|
||
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document` (docx)
|
||
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` (xlsx)
|
||
- `application/vnd.openxmlformats-officedocument.presentationml.presentation` (pptx)
|
||
|
||
**Réponse `201`**
|
||
|
||
```json
|
||
{
|
||
"document_id": "string",
|
||
"name": "string",
|
||
"mime_type": "string",
|
||
"size": number
|
||
}
|
||
```
|
||
|
||
**Erreurs** : `400` type non supporté ; `413` fichier trop volumineux (`MAX_UPLOAD_BYTES`).
|
||
|
||
### `GET /documents`
|
||
|
||
Liste les documents de la clé.
|
||
|
||
**Réponse `200`** : tableau d’objets métadonnées (structure définie par le stockage SQLite — champs typiques : id, nom, mime, taille, dates).
|
||
|
||
### `GET /documents/{document_id}`
|
||
|
||
Métadonnées d’un document (propriétaire = clé courante).
|
||
|
||
**Erreurs** : `404` si absent ou non propriétaire.
|
||
|
||
### `GET /documents/{document_id}/file`
|
||
|
||
Téléchargement du fichier binaire ; `Content-Type` et nom de fichier alignés sur les métadonnées.
|
||
|
||
### `POST /documents/{document_id}/commands`
|
||
|
||
Applique une liste de commandes au contenu. **Implémenté pour docx uniquement** ; xlsx/pptx renvoient **400** (« not implemented yet »).
|
||
|
||
**Corps JSON**
|
||
|
||
```json
|
||
{
|
||
"commands": [
|
||
{
|
||
"type": "replaceText",
|
||
"search": "texte à chercher",
|
||
"replace": "remplacement"
|
||
},
|
||
{
|
||
"type": "insertParagraph",
|
||
"text": "nouveau paragraphe",
|
||
"position": "end"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| `type` | Champs | Description |
|
||
|--------|--------|-------------|
|
||
| `replaceText` | `search` (non vide), `replace` | Première occurrence remplacée dans paragraphes / tableaux |
|
||
| `insertParagraph` | `text`, `position` optionnel `end` (défaut) ou `start` | Insère un paragraphe |
|
||
|
||
**Réponse `200`** : `{ "document_id", "size" }` (taille après écriture).
|
||
|
||
**Erreurs** : `400` commande ou MIME invalide ; `404` document absent ou autre clé.
|
||
|
||
### `DELETE /documents/{document_id}`
|
||
|
||
Supprime métadonnées et fichier.
|
||
|
||
**Réponse `204`** sans corps.
|
||
|
||
**Erreurs** : `404` si absent ou non propriétaire.
|
||
|
||
## Variables d’environnement (rappel)
|
||
|
||
| Variable | Rôle |
|
||
|----------|------|
|
||
| `API_KEYS` | Liste de clés autorisées (obligatoire en production) |
|
||
| `STORAGE_PATH` | Fichiers sur disque |
|
||
| `DATABASE_PATH` | SQLite métadonnées |
|
||
| `MAX_UPLOAD_BYTES` | Taille max upload |
|
||
| `RATE_LIMIT_PER_MINUTE` | Plafond requêtes / minute / clé |
|
||
|
||
Voir [`services/local-office/.env.example`](../../services/local-office/.env.example).
|