Bruno Charest
cc99fea20a
- Implement tests for database generator to ensure proper session handling. - Create tests for EXIF extraction and conversion functions. - Add tests for image-related endpoints, ensuring proper data retrieval and isolation between clients. - Develop tests for OCR functionality, including language detection and text extraction. - Introduce tests for the image processing pipeline, covering success and failure scenarios. - Validate rate limiting functionality and ensure independent counters for different clients. - Implement scraper tests to verify HTML content fetching and error handling. - Add unit tests for various services, including storage and filename generation. - Establish worker entry point for ARQ to handle background image processing tasks.
243 lines
7.1 KiB
Markdown
243 lines
7.1 KiB
Markdown
# Guide d'utilisation de l'API Imago
|
|
|
|
## 📍 Sommaire
|
|
- [🔐 Authentification](#-authentification)
|
|
- [🛡️ Scopes (Permissions)](#-scopes-permissions)
|
|
- [📊 Plans et Rate Limiting](#-plans-et-rate-limiting)
|
|
- [👥 Gestion des Clients (Admin uniquement)](#-gestion-des-clients-admin-uniquement)
|
|
- [📁 Multi-tenancy et Isolation](#-multi-tenancy-et-isolation)
|
|
- [📖 Référence des Endpoints](#-référence-des-endpoints)
|
|
- [📸 Gestion des Images](#-gestion-des-images)
|
|
- [🤖 Intelligence Artificielle](#-intelligence-artificielle)
|
|
- [🔑 Administration (Admin uniquement)](#-administration-admin-uniquement)
|
|
- [🏥 Santé et Status](#-santé-et-status)
|
|
- [🚀 Exemples Rapides](#-exemples-rapides)
|
|
|
|
---
|
|
|
|
## 🔐 Authentification
|
|
|
|
Tous les endpoints (sauf `/health` et `/`) nécessitent une authentification via une **Clé API**.
|
|
|
|
### Header Authorization
|
|
|
|
Vous devez inclure votre clé dans le header `Authorization` de chaque requête :
|
|
|
|
```http
|
|
Authorization: Bearer VOTRE_CLE_API_SECRET
|
|
```
|
|
|
|
> [!WARNING]
|
|
> Traitez votre clé API comme un mot de passe. Ne la partagez jamais et ne l'incluez pas dans du code client (frontend) accessible publiquement.
|
|
|
|
---
|
|
|
|
## 🛡️ Scopes (Permissions)
|
|
|
|
L'accès aux fonctionnalités est contrôlé par des **scopes**. Chaque clé API est limitée à un ensemble de permissions :
|
|
|
|
| Scope | Description | Fonctions incluses |
|
|
|-------|-------------|-------------------|
|
|
| `images:read` | Lecture seule | Lister les images, voir les détails, EXIF, OCR, AI. |
|
|
| `images:write` | Écriture | Uploader des images, relancer le pipeline de traitement. |
|
|
| `images:delete`| Suppression | Supprimer définitivement des images. |
|
|
| `ai:use` | Utilisation IA | Résumé d'URL, rédaction de tâches. |
|
|
| `admin` | Administration | Gérer les clients API, voir les clés, modifier les plans. |
|
|
|
|
---
|
|
|
|
## 📊 Plans et Rate Limiting
|
|
|
|
Le système applique des limites de requêtes (Rate Limits) basées sur le **Plan** de votre client. Les compteurs sont réinitialisés toutes les heures.
|
|
|
|
| Plan | Uploads / heure | Requêtes AI / heure |
|
|
|------|-----------------|---------------------|
|
|
| `free` | 20 | 50 |
|
|
| `standard` | 100 | 200 |
|
|
| `premium` | 500 | 1000 |
|
|
|
|
*Les requêtes de lecture (`GET`) ne sont pas limitées par défaut.*
|
|
|
|
---
|
|
|
|
## 👥 Gestion des Clients (Admin uniquement)
|
|
|
|
Si vous avez le scope `admin`, vous pouvez gérer les accès.
|
|
|
|
### Créer un nouveau client
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/auth/clients \
|
|
-H "Authorization: Bearer CLE_ADMIN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "Application Mobile",
|
|
"scopes": ["images:read", "images:write", "ai:use"],
|
|
"plan": "standard"
|
|
}'
|
|
```
|
|
|
|
**Réponse (Importante) :**
|
|
```json
|
|
{
|
|
"id": "uuid-...",
|
|
"api_key": "cle_generee_en_clair_une_seule_fois",
|
|
"name": "Application Mobile",
|
|
...
|
|
}
|
|
```
|
|
> [!CAUTION]
|
|
> La clé API n'est affichée **qu'une seule fois** à la création. Stockez-la immédiatement de manière sécurisée.
|
|
|
|
### Régénérer une clé (Rotation)
|
|
|
|
En cas de compromission, invalidez l'ancienne clé et générez-en une nouvelle :
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/auth/clients/{id}/rotate-key \
|
|
-H "Authorization: Bearer CLE_ADMIN"
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 Multi-tenancy et Isolation
|
|
|
|
L'API est **multi-tenant**. Cela signifie que :
|
|
- Vous ne voyez **que** les images uploadées avec votre clé.
|
|
- Les IDs d'images sont globaux, mais si vous tentez d'accéder à l'ID d'un autre client, vous recevrez une erreur `404 Not Found`.
|
|
- Vos fichiers physiques sont stockés dans un sous-répertoire dédié sur le serveur (`/data/uploads/{votre_client_id}/`).
|
|
|
|
---
|
|
|
|
## 📖 Référence des Endpoints
|
|
|
|
### 📸 Gestion des Images
|
|
|
|
#### Lister les images
|
|
`GET /images`
|
|
- **Scope required** : `images:read`
|
|
- **Query Params** :
|
|
- `page` : Numéro de page (défaut: 1)
|
|
- `page_size` : Taille de page (défaut: 20, max: 100)
|
|
- `tag` : Filtrer par tag AI
|
|
- `status` : Filtrer par statut (`pending`, `processing`, `done`, `error`)
|
|
- `search` : Recherche textuelle dans le nom, la description AI ou l'OCR.
|
|
|
|
#### Uploader une image
|
|
`POST /images/upload`
|
|
- **Scope required** : `images:write`
|
|
- **Body** : `multipart/form-data`
|
|
- `file` : Le fichier image (JPEG, PNG, WebP, etc.)
|
|
- **Note** : Lance automatiquement le pipeline AI en arrière-plan.
|
|
|
|
#### Détail complet d'une image
|
|
`GET /images/{id}`
|
|
- **Scope required** : `images:read`
|
|
- **Description** : Retourne toutes les données (Source, EXIF, OCR, AI).
|
|
|
|
#### Statut du traitement
|
|
`GET /images/{id}/status`
|
|
- **Scope required** : `images:read`
|
|
- **Description** : Pour savoir si l'analyse par l'IA est terminée.
|
|
|
|
#### Métadonnées spécifiques
|
|
- `GET /images/{id}/exif` : Données techniques de l'appareil et GPS.
|
|
- `GET /images/{id}/ocr` : Texte extrait de l'image.
|
|
- `GET /images/{id}/ai` : Description textuelle et tags générés.
|
|
|
|
#### Retraitement
|
|
`POST /images/{id}/reprocess`
|
|
- **Scope required** : `images:write`
|
|
- **Description** : Réinitialise et relance le pipeline d'analyse AI.
|
|
|
|
#### Suppression
|
|
`DELETE /images/{id}`
|
|
- **Scope required** : `images:delete`
|
|
- **Description** : Supprime l'entrée en base et les fichiers sur le disque.
|
|
|
|
#### Tags globaux
|
|
`GET /images/tags/all`
|
|
- **Scope required** : `images:read`
|
|
- **Description** : Liste tous les tags uniques utilisés par le client.
|
|
|
|
---
|
|
|
|
### 🤖 Intelligence Artificielle
|
|
|
|
#### Résumé d'URL
|
|
`POST /ai/summarize`
|
|
- **Scope required** : `ai:use`
|
|
- **Body** (JSON) :
|
|
```json
|
|
{
|
|
"url": "https://...",
|
|
"language": "français"
|
|
}
|
|
```
|
|
|
|
#### Rédaction de tâche
|
|
`POST /ai/draft-task`
|
|
- **Scope required** : `ai:use`
|
|
- **Body** (JSON) :
|
|
```json
|
|
{
|
|
"description": "Texte libre décrivant la tâche",
|
|
"context": "Contexte optionnel",
|
|
"language": "fr"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 🔑 Administration (Admin uniquement)
|
|
*Nécessite le scope `admin`.*
|
|
|
|
- `POST /auth/clients` : Créer un client (retourne la clé).
|
|
- `GET /auth/clients` : Lister tous les clients.
|
|
- `GET /auth/clients/{id}` : Voir les détails d'un client.
|
|
- `PATCH /auth/clients/{id}` : Modifier un client (nom, scopes, plan).
|
|
- `POST /auth/clients/{id}/rotate-key` : Changer la clé API.
|
|
- `DELETE /auth/clients/{id}` : Désactiver un client (suspension d'accès).
|
|
|
|
---
|
|
|
|
### 🏥 Santé et Status
|
|
Ces endpoints sont **publics** et ne nécessitent aucune clé API.
|
|
|
|
- `GET /` : Informations de base sur l'application (Version, Status).
|
|
- `GET /health` : Vérification complète de l'état (AI configurée, OCR actif, Modèle utilisé).
|
|
|
|
---
|
|
|
|
## 🚀 Exemples Rapides
|
|
|
|
### Lister mes images (Python / httpx)
|
|
|
|
```python
|
|
import httpx
|
|
|
|
headers = {"Authorization": "Bearer ma_super_cle"}
|
|
r = httpx.get("http://localhost:8000/images", headers=headers)
|
|
|
|
for img in r.json()["items"]:
|
|
print(f"ID: {img['id']} | Name: {img['original_name']}")
|
|
```
|
|
|
|
### Uploader une image (Node.js / Axios)
|
|
|
|
```javascript
|
|
const axios = require('axios');
|
|
const fs = require('fs');
|
|
const FormData = require('form-data');
|
|
|
|
const form = new FormData();
|
|
form.append('file', fs.createReadStream('vacances.jpg'));
|
|
|
|
axios.post('http://localhost:8000/images/upload', form, {
|
|
headers: {
|
|
...form.getHeaders(),
|
|
'Authorization': 'Bearer ma_super_cle'
|
|
}
|
|
}).then(console.log);
|
|
```
|