seo-generator-server/API.md

# API Documentation - SEO Generator Server

## 🚀 Endpoints API Disponibles

### Base URL
```
http://localhost:3002/api
```

---

## 📝 GESTION ARTICLES

### GET /api/articles
Récupère la liste des articles générés.

**Query Parameters:**
- `limit` (optional): Nombre d'articles à retourner (défaut: 50)
- `offset` (optional): Position de départ (défaut: 0)
- `project` (optional): Filtrer par projet
- `status` (optional): Filtrer par statut

**Response:**
```json
{
  "success": true,
  "data": {
    "articles": [...],
    "total": 150,
    "limit": 50,
    "offset": 0
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}
```

### GET /api/articles/:id
Récupère un article spécifique.

**Query Parameters:**
- `format` (optional): Format de réponse (`json`, `html`, `text`)

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "article_123",
    "content": "...",
    "metadata": {...}
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}
```

### POST /api/articles
Crée un nouvel article.

**Request Body:**
```json
{
  "keyword": "plaque personnalisée",
  "project": "client_xyz",
  "config": {
    "selectiveStack": "standardEnhancement",
    "adversarialMode": "light",
    "humanSimulationMode": "none",
    "patternBreakingMode": "none"
  },
  "personalityPreference": {
    "nom": "Marc",
    "style": "professionnel"
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "article_456",
    "article": {...},
    "config": {...}
  },
  "message": "Article créé avec succès",
  "timestamp": "2025-09-16T00:00:00.000Z"
}
```

---

## 📁 GESTION PROJETS

### GET /api/projects
Récupère la liste des projets.

**Response:**
```json
{
  "success": true,
  "data": {
    "projects": [...],
    "total": 25
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}
```

### POST /api/projects
Crée un nouveau projet.

**Request Body:**
```json
{
  "name": "Projet Client XYZ",
  "description": "Génération de contenu SEO pour le client XYZ",
  "config": {
    "defaultPersonality": "Marc",
    "selectiveStack": "fullEnhancement"
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "project_789",
    "name": "Projet Client XYZ",
    "description": "...",
    "config": {...},
    "createdAt": "2025-09-16T00:00:00.000Z",
    "articlesCount": 0
  },
  "message": "Projet créé avec succès"
}
```

---

## 📋 GESTION TEMPLATES

### GET /api/templates
Récupère la liste des templates XML.

**Response:**
```json
{
  "success": true,
  "data": {
    "templates": [...],
    "total": 12
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}
```

### POST /api/templates
Crée un nouveau template.

**Request Body:**
```json
{
  "name": "Template Article Blog",
  "content": "<?xml version='1.0' encoding='UTF-8'?>...",
  "description": "Template pour articles de blog SEO",
  "category": "blog"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "template_101",
    "name": "Template Article Blog",
    "content": "...",
    "description": "...",
    "category": "blog",
    "createdAt": "2025-09-16T00:00:00.000Z"
  },
  "message": "Template créé avec succès"
}
```

---

## ⚙️ CONFIGURATION

### GET /api/config/personalities
Récupère la configuration des personnalités.

**Response:**
```json
{
  "success": true,
  "data": {
    "personalities": [
      {
        "nom": "Marc",
        "style": "professionnel et précis",
        "description": "...",
        "connecteurs": ["par ailleurs", "en effet"]
      }
    ],
    "total": 15
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}
```

---

## 📊 MONITORING

### GET /api/health
Health check du système.

**Response:**
```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2025-09-16T00:00:00.000Z",
    "version": "1.0.0",
    "uptime": 3600,
    "memory": {...},
    "environment": "development"
  }
}
```

### GET /api/metrics
Métriques système et statistiques.

**Response:**
```json
{
  "success": true,
  "data": {
    "articles": {
      "total": 1250,
      "recent": 45
    },
    "projects": {
      "total": 25
    },
    "templates": {
      "total": 12
    },
    "system": {
      "uptime": 3600,
      "memory": {...},
      "platform": "linux",
      "nodeVersion": "v24.3.0"
    }
  },
  "timestamp": "2025-09-16T00:00:00.000Z"
}
```

---

## 🎭 ENDPOINTS EXISTANTS (Compatibilité)

### GET /api/status
Statut du serveur.

### GET /api/personalities
Liste des personnalités (legacy).

### POST /api/generate-simple
Génération simple avec mot-clé.

### POST /api/test-modulaire
Test modulaire individuel.

### POST /api/workflow-modulaire
Workflow complet modulaire.

### POST /api/benchmark-modulaire
Benchmark des stacks.

---

## 🔧 Configuration par Défaut

### Stacks Selective Enhancement
- `lightEnhancement`
- `standardEnhancement`
- `fullEnhancement`
- `creativeEnhancement`
- `adaptive`

### Modes Adversarial
- `none`
- `light`
- `standard`
- `heavy`
- `adaptive`

### Modes Human Simulation
- `none`
- `lightSimulation`
- `standardSimulation`
- `heavySimulation`
- `personalityFocus`
- `adaptive`

### Modes Pattern Breaking
- `none`
- `syntaxFocus`
- `connectorsFocus`
- `structureFocus`
- `styleFocus`
- `comprehensiveFocus`
- `adaptive`

---

## 🚨 Gestion d'Erreurs

Toutes les erreurs retournent un format standard :

```json
{
  "success": false,
  "error": "Description de l'erreur",
  "message": "Message détaillé",
  "timestamp": "2025-09-16T00:00:00.000Z"
}
```

### Codes d'Erreur
- `400`: Bad Request - Paramètres invalides
- `404`: Not Found - Ressource non trouvée
- `500`: Internal Server Error - Erreur serveur

---

## 📝 Exemples d'Utilisation

### Créer un article simple
```bash
curl -X POST http://localhost:3002/api/articles \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "plaque personnalisée",
    "project": "test",
    "config": {
      "selectiveStack": "standardEnhancement",
      "adversarialMode": "light"
    }
  }'
```

### Récupérer les métriques
```bash
curl http://localhost:3002/api/metrics
```

### Créer un projet
```bash
curl -X POST http://localhost:3002/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mon Projet SEO",
    "description": "Projet de test"
  }'
```

---

## 🔄 Intégration avec Google Sheets

L'API utilise automatiquement l'intégration Google Sheets pour :
- Récupérer les données de lignes spécifiques
- Charger les 15 personnalités disponibles
- Sauvegarder les articles générés
- Maintenir la cohérence des données