Imago/docs/API_GUIDE.md

Guide d'utilisation de l'API Imago

Bienvenue dans la documentation officielle de l'API REST d'Imago. Note : Tous les terminaux (endpoints) principaux présentés ici sont désormais servis sous le préfixe /api/v1/ dans l'application locale.

📍 Sommaire

• 🔐 Authentification
• 🛡️ Scopes (Permissions)
• 📊 Plans et Rate Limiting
• 👥 Gestion des Clients (Admin uniquement)
• 📁 Multi-tenancy et Isolation
• 📖 Référence des Endpoints
  • 📸 Gestion des Images
  • 🤖 Intelligence Artificielle
  • 🔑 Administration (Admin uniquement)
  • 🏥 Santé et Status
• 🚀 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 :

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

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) :

{
  "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 :

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 /api/v1/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 /api/v1/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 /api/v1/images/{id}

• Scope required : images:read
• Description : Retourne toutes les données (Source, EXIF, OCR, AI).

Statut du traitement

GET /api/v1/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 /api/v1/images/{id}/exif : Données techniques de l'appareil et GPS.
• GET /api/v1/images/{id}/ocr : Texte extrait de l'image.
• GET /api/v1/images/{id}/ai : Description textuelle et tags générés.

Retraitement

POST /api/v1/images/{id}/reprocess

• Scope required : images:write
• Description : Réinitialise et relance le pipeline d'analyse AI.

Suppression

DELETE /api/v1/images/{id}

• Scope required : images:delete
• Description : Supprime l'entrée en base et les fichiers sur le disque.

Tags globaux

GET /api/v1/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 /api/v1/ai/summarize

• Scope required : ai:use
• Body (JSON) :

  {
    "url": "https://...",
    "language": "français"
  }
  

Rédaction de tâche

POST /api/v1/ai/draft-task

• Scope required : ai:use
• Body (JSON) :

  {
    "description": "Texte libre décrivant la tâche",
    "context": "Contexte optionnel",
    "language": "fr"
  }
  

---

🔑 Administration (Admin uniquement)

Nécessite le scope admin.

• POST /api/v1/auth/clients : Créer un client (retourne la clé).
• GET /api/v1/auth/clients : Lister tous les clients.
• GET /api/v1/auth/clients/{id} : Voir les détails d'un client.
• PATCH /api/v1/auth/clients/{id} : Modifier un client (nom, scopes, plan).
• POST /api/v1/auth/clients/{id}/rotate-key : Changer la clé API.
• DELETE /api/v1/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)

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)

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);