Documentation API

Référence technique pour l'API REST et l'intégration WebSocket de Resolflow

Référence API interne

Cette documentation décrit l'API REST interne de Resolflow pour comprendre le fonctionnement de la plateforme. Resolflow est une application autonome, pas une API de plateforme pour les intégrations tierces. Si vous devez interagir avec Resolflow par programmation, utilisez plutôt le protocole MCP.

Aperçu de l'API

Architecture et capacités

Conception RESTful

Méthodes HTTP standard (GET, POST, PATCH, DELETE)

Mises à jour en temps réel

WebSocket pour les notifications en direct

Réponses JSON

Format de données cohérent

Authentification

Authentification basée sur JWT avec double jeton

Système de jetons

Jeton d'accès
15 minutes

Jeton à courte durée stocké dans un cookie HTTP-only. Utilisé pour les requêtes API.

Jeton de rafraîchissement
7 jours

Jeton à longue durée pour obtenir de nouveaux jetons d'accès sans reconnexion.

# Connexion pour obtenir des jetons

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "yourpassword"
}

Response:
{
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

# Utiliser le jeton d'accès dans les requêtes

GET /api/workspaces
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Points de terminaison API principaux

Ressources et opérations principales

Authentification

POST
/api/auth/register

Créer un nouveau compte

POST
/api/auth/login

Connexion avec e-mail/mot de passe

POST
/api/auth/refresh

Obtenir un nouveau jeton d'accès

POST
/api/auth/logout

Effacer les jetons et terminer la session

GET
/api/auth/me

Obtenir les infos de l'utilisateur actuel

Espaces de travail

GET
/api/workspaces

Lister tous les espaces de travail

GET
/api/workspaces/:id

Obtenir les détails de l'espace de travail

POST
/api/workspaces

Créer un nouvel espace de travail

PATCH
/api/workspaces/:id

Mettre à jour l'espace de travail

DELETE
/api/workspaces/:id

Supprimer l'espace de travail

Projets

GET
/api/workspaces/:workspaceId/projects

Lister les projets de l'espace de travail

POST
/api/workspaces/:workspaceId/projects

Créer un projet

PATCH
/api/projects/:id

Mettre à jour les paramètres du projet

Tâches & Todos

GET
/api/projects/:projectId/tasks

Lister les tâches

POST
/api/projects/:projectId/tasks

Créer une tâche

GET
/api/tasks/:taskId/todos

Lister les todos d'une tâche

PATCH
/api/todos/:id

Mettre à jour le statut d'un todo

Agents & Connexions

GET
/api/workspaces/:workspaceId/agents

Lister les agents MCP

POST
/api/projects/:projectId/tokens

Générer un jeton MCP

GET
/api/workspaces/:workspaceId/repos

Lister les dépôts GitHub connectés

Orchestrateur

POST
/api/orchestrator/suggest-tasks

Génération de tâches par IA

GET
/api/orchestrator/inbox

Obtenir les messages de l'orchestrateur

POST
/api/orchestrator/ask

Demander conseil à l'orchestrateur

Rapports & Analyses

GET
/api/projects/:projectId/reports

Lister les rapports

GET
/api/reports/:id

Obtenir les détails du rapport

Mises à jour en temps réel WebSocket

Notifications en direct et synchronisation des données

Connectez-vous au serveur WebSocket pour les mises à jour en temps réel des tâches, todos, messages de l'orchestrateur et rapports.

# Se connecter au WebSocket

// Send authentication
{
  "type": "auth",
  "token": "your-access-token"
}

// Subscribe to workspace updates
{
  "type": "subscribe",
  "workspaceId": "workspace-uuid"
}

// Receive updates
{
  "type": "task_updated",
  "data": {
    "taskId": "uuid",
    "status": "in_progress",
    "updatedBy": "agent-name"
  }
}

Types d'événements

task_created

Nouvelle tâche ajoutée

task_updated

Statut de tâche modifié

todo_updated

Mise à jour de progression du todo

orchestrator_message

Nouveau conseil de l'IA

report_generated

Nouveau rapport d'analyse

loop_signal

Agent bloqué détecté

Exemple : Créer une tâche

Flux complet de requête et réponse

Requête

POST /api/projects/550e8400-e29b-41d4-a716-446655440000/tasks
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "title": "Add dark mode support",
  "description": "Implement dark mode toggle with system preference detection",
  "type": "feature",
  "priority": "medium"
}

Réponse (201 Created)

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "title": "Add dark mode support",
  "description": "Implement dark mode toggle with system preference detection",
  "type": "feature",
  "priority": "medium",
  "status": "not_started",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "user-uuid",
  "createdAt": "2024-02-12T10:30:00Z",
  "updatedAt": "2024-02-12T10:30:00Z"
}

Limites de débit & Bonnes pratiques

Directives pour l'utilisation de l'API

Limites de débit

Aucune limite de débit n'est actuellement appliquée pour les instances auto-hébergées. Pour les déploiements en production, envisagez d'implémenter une limitation de débit selon votre infrastructure.

Bonnes pratiques

  • • Utilisez WebSocket pour les données en temps réel au lieu du polling
  • • Mettez en cache les réponses côté client (React Query s'en charge)
  • • Groupez les opérations si possible (création groupée de todos)
  • • Gérez le rafraîchissement du jeton automatiquement avec des intercepteurs
  • • Utilisez des mises à jour optimistes pour une meilleure UX

Gestion des erreurs

Codes de statut HTTP standard :

  • • 200 - Succès
  • • 201 - Créé
  • • 400 - Requête invalide (erreurs de validation)
  • • 401 - Non autorisé (jeton invalide/expiré)
  • • 403 - Interdit (permissions insuffisantes)
  • • 404 - Introuvable
  • • 500 - Erreur serveur