33800 Docs

← Retour

Connectors Hub v3 - API autonome + Front séparé

Date : 25/01/2026 Status : PROPOSITION Projets :

Vision

L'API se suffit à elle-même : tout est faisable via API REST. Le front est un consommateur comme un autre.

  1. Auth complète (login, register, reset password, disable)
  2. Gérer ses connecteurs (CRUD)
  3. Lier ses comptes (OAuth, API keys, tokens)
  4. Explorer les APIs (endpoints, schemas)
  5. Tracer les actions (audit logs)
  6. Versionner les endpoints (changelog)

Architecture

GitLab/
├── connectors-api/              # Backend Elysia (EXISTANT)
│   ├── src/
│   │   ├── services/
│   │   │   ├── registry.ts
│   │   │   ├── discovery.ts
│   │   │   ├── userAuth.ts      # À enrichir (reset password)
│   │   │   ├── autodiscovery.ts # NOUVEAU
│   │   │   ├── audit.ts         # NOUVEAU - Logs
│   │   │   └── versioning.ts    # NOUVEAU - Versions
│   │   └── index.ts
│   └── package.json
│
└── connectors-front/            # NOUVEAU PROJET SÉPARÉ
    ├── src/
    │   ├── routes/
    │   │   ├── index.tsx
    │   │   ├── auth/
    │   │   ├── connectors/
    │   │   └── admin/
    │   ├── components/
    │   └── lib/
    │       └── api.ts           # Client connectors-api
    └── package.json

Fonctionnalités Front

1. Auth (Login/Register/Reset/Settings)

Page Route Description
Login /auth/login Email + password
Register /auth/register Création compte
Forgot /auth/forgot-password Demande reset
Reset /auth/reset-password?token=xxx Nouveau mot de passe
Settings /auth/settings Profil, change password, disable account

Reset password flow :

  1. User entre son email → POST /api/auth/forgot-password
  2. API envoie email avec lien (token temporaire 1h)
  3. User clique → page reset avec token
  4. User entre nouveau password → POST /api/auth/reset-password

Disable account :

2. Connecteurs (CRUD)

Page Route Description
Liste /connectors Cards avec status connexion
Détail /connectors/[id] Vue complète
Créer /connectors/new Wizard création
Modifier /connectors/[id]/edit Form édition

Wizard création :

Étape 1: Infos de base
  - Nom, display_name, description
  - Base URL de l'API
  - Icône (upload ou URL)

Étape 2: Authentification
  - Type: OAuth2 / API Key / Bearer / Basic / Custom
  - Config selon type (URLs, scopes, headers...)

Étape 3: Discovery
  - Auto-detect swagger
  - Ou URL swagger manuelle
  - Ou exploration auto

Étape 4: Validation
  - Test de connexion
  - Preview endpoints découverts

3. Lier un compte (Auth connecteur)

Type Interface
OAuth2 Bouton "Connecter" → popup OAuth → callback
API Key Input texte + bouton "Sauvegarder"
Bearer Input token + expiration optionnelle
Basic Inputs user/password
Custom Form dynamique selon auth_config

UI intuitive :

┌─────────────────────────────────────────────┐
│  GitHub                          ● Connecté │
│  ─────────────────────────────────────────  │
│  Compte: gouroubleu                         │
│  Expire: Jamais                             │
│  Scopes: repo, user, read:org               │
│                                             │
│  [Déconnecter]  [Rafraîchir]  [Voir logs]  │
└─────────────────────────────────────────────┘

4. Explorer les endpoints

Vue Description
Liste Table triable avec filtres (entity, action, method)
Détail Schema request/response, relations, tester
Tester Form auto-généré depuis schema, exécution live

Tester un endpoint :

┌─────────────────────────────────────────────┐
│  POST /user/repos                           │
│  ─────────────────────────────────────────  │
│                                             │
│  name*:        [mon-nouveau-repo    ]       │
│  description:  [Description du repo ]       │
│  private:      [x] Oui                      │
│  auto_init:    [ ] Non                      │
│                                             │
│  [Exécuter]                                 │
│                                             │
│  ─── Réponse ───                            │
│  Status: 201 Created                        │
│  { "id": 123, "name": "mon-nouveau-repo" }  │
└─────────────────────────────────────────────┘

API Complète (autonome)

Endpoints Auth

Méthode Endpoint Description
POST /api/auth/register Créer un compte
POST /api/auth/login Connexion → JWT
POST /api/auth/logout Déconnexion
POST /api/auth/refresh Rafraîchir token
GET /api/auth/me Profil utilisateur
PUT /api/auth/me Modifier profil
POST /api/auth/change-password Changer mot de passe (connecté)
POST /api/auth/forgot-password Demander reset (envoie email)
POST /api/auth/reset-password Reset avec token
POST /api/auth/disable-account Désactiver compte
POST /api/auth/verify-email Vérifier email (optionnel)

Endpoints Connecteurs

Méthode Endpoint Description
GET /api/connectors Liste tous les connecteurs
POST /api/connectors Créer connecteur (+ auto-discovery)
GET /api/connectors/:id Détail connecteur
PUT /api/connectors/:id Modifier connecteur
DELETE /api/connectors/:id Supprimer connecteur
POST /api/connectors/:id/rediscover Relancer discovery
GET /api/connectors/:id/schema Schema complet
GET /api/connectors/:id/endpoints Liste endpoints
GET /api/connectors/:id/logs Logs du connecteur

Endpoints Auth Connecteur (lier compte)

Méthode Endpoint Description
GET /api/user/connectors/:id Mon status connexion
GET /api/user/connectors/:id/auth URL OAuth ou instructions
POST /api/user/connectors/:id/token Sauver token/API key
DELETE /api/user/connectors/:id/auth Révoquer
GET /api/connectors/:id/callback Callback OAuth

Endpoints Endpoints (meta)

Méthode Endpoint Description
GET /api/endpoints/:id Détail endpoint
PUT /api/endpoints/:id Modifier endpoint
DELETE /api/endpoints/:id Supprimer endpoint
GET /api/endpoints/:id/versions Historique versions
GET /api/endpoints/:id/versions/:v Détail version
POST /api/endpoints/:id/rollback/:v Rollback

Endpoints Audit

Méthode Endpoint Description
GET /api/audit/logs Liste logs (filtres)
GET /api/audit/logs/:id Détail log
GET /api/audit/stats Stats globales

Endpoint Proxy Fetch

Méthode Endpoint Description
POST /api/fetch Exécuter requête via connecteur

Nouvelles fonctionnalités Backend

1. Audit Logs

Table audit_logs :

CREATE TABLE audit_logs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  connector_id UUID REFERENCES config(id),
  action VARCHAR(50) NOT NULL,  -- 'fetch', 'create', 'update', 'delete', 'auth'
  resource VARCHAR(100),         -- 'connector', 'endpoint', 'token'
  resource_id UUID,
  details JSONB,                 -- Payload, response status, etc.
  ip_address VARCHAR(50),
  user_agent TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_audit_user ON audit_logs(user_id, created_at DESC);
CREATE INDEX idx_audit_connector ON audit_logs(connector_id, created_at DESC);

Actions loggées : | Action | Quand | |--------|-------| | auth.login | Connexion utilisateur | | auth.logout | Déconnexion | | connector.create | Création connecteur | | connector.update | Modification connecteur | | connector.delete | Suppression connecteur | | connector.auth | Liaison compte (OAuth, token) | | connector.revoke | Révocation token | | fetch.execute | Appel API via proxy | | endpoint.discover | Découverte endpoint | | endpoint.import | Import swagger |

Endpoints API :

GET /api/audit/logs              # Liste logs (filtres: user, connector, action, date)
GET /api/audit/logs/:id          # Détail log
GET /api/connectors/:id/logs     # Logs d'un connecteur

2. Versioning des endpoints

Table endpoint_versions :

CREATE TABLE endpoint_versions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  endpoint_id UUID REFERENCES endpoints(id) ON DELETE CASCADE,
  version INT NOT NULL,

  -- Snapshot des données
  path VARCHAR(500),
  method VARCHAR(10),
  request_schema JSONB,
  response_schema JSONB,
  parameters JSONB,

  -- Métadonnées
  change_type VARCHAR(20),       -- 'created', 'updated', 'deleted'
  change_summary TEXT,
  changed_by UUID REFERENCES users(id),
  created_at TIMESTAMPTZ DEFAULT NOW(),

  UNIQUE(endpoint_id, version)
);

CREATE INDEX idx_version_endpoint ON endpoint_versions(endpoint_id, version DESC);

Logique :

Endpoints API :

GET /api/endpoints/:id/versions           # Historique versions
GET /api/endpoints/:id/versions/:v        # Détail version
POST /api/endpoints/:id/rollback/:v       # Rollback
GET /api/endpoints/:id/diff/:v1/:v2       # Diff entre versions

Stack technique Front

Lib Usage
Qwik Framework
Qwik City Routing
TailwindCSS Styling
DaisyUI Composants UI
@tanstack/query Cache API

Phases d'implémentation

Phase 1 : API - Auth complète

  1. [x] POST /api/auth/forgot-password (envoie email via Supabase)
  2. [ ] POST /api/auth/reset-password (avec token) - TODO: notif-logger template
  3. [x] POST /api/auth/change-password
  4. [x] PUT /api/auth/me (modifier profil)
  5. [x] POST /api/auth/disable-account
  6. [ ] Table password_reset_tokens - Géré par Supabase GoTrue

Phase 2 : API - Auto-discovery [TERMINÉ]

  1. [x] Service autodiscovery.ts
  2. [x] Recherche intelligente swagger (13 URLs courantes)
  3. [x] Trigger auto à la création de connecteur
  4. [x] POST /api/connectors/:id/rediscover

Phase 3 : API - Audit logs [TERMINÉ]

  1. [x] Service audit.ts
  2. [x] Table audit_logs (migration 002)
  3. [x] Logger auth.login avec IP/user-agent
  4. [x] Endpoints /api/audit/logs, /api/audit/logs/:id, /api/audit/stats
  5. [x] GET /api/connectors/:id/logs

Phase 4 : API - Versioning endpoints [TERMINÉ]

  1. [x] Service versioning.ts
  2. [x] Table endpoint_versions (migration 003)
  3. [x] Support rollback vers version précédente
  4. [x] Endpoints /api/endpoints/:id/versions, /api/endpoints/:id/rollback/:v
  5. [x] Diff entre versions /api/endpoints/:id/diff/:v1/:v2

Phase 5 : Front - Projet connectors-front

  1. [ ] Init projet Qwik + TailwindCSS + DaisyUI
  2. [ ] Auth (login, register, forgot, reset, settings)
  3. [ ] Connecteurs (liste, création wizard, détail)
  4. [ ] Lier compte (OAuth popup, forms API key)
  5. [ ] Explorer endpoints + testeur
  6. [ ] Audit logs

Décisions attendues

  1. Envoi email reset password :

    • Via notif-logger (port 5300) - service existant
    • Nécessite modif notif-logger pour supporter to dynamique
    • Template email à créer

  2. Déploiement front :

    • SSR sur prod-portainer (port 5401) ?
    • Domaine : connectors.33800.nowhere84.com ?

  3. Priorité :

    • Commencer par API complète (phases 1-4) ?
    • Ou front en parallèle ?

  4. Versioning : snapshot complet ou delta/diff ?