veza/apps/web/MIGRATION_GUIDE.md

Guide de Migration : ApiService → apiClient

Vue d'ensemble

ApiService est déprécié en faveur de apiClient pour unifier les clients API et éviter la duplication de code.

Pourquoi migrer ?

• Unification : Un seul client API au lieu de deux
• Maintenance : Moins de code à maintenir
• Cohérence : Même comportement partout (gestion d'erreurs, refresh token, etc.)
• Performance : Pas de duplication d'instances Axios

Comment migrer

Import

Avant :

import { apiService } from '@/services/api';

Après :

import { apiClient } from '@/services/api/client';

Méthodes d'authentification

Avant :

const { user, tokens } = await apiService.login(credentials);
const user = await apiService.getCurrentUser();
await apiService.logout();

Après :

import { authApi } from '@/features/auth/api/authApi';

const response = await authApi.login(credentials);
const user = await authApi.getMe();
await authApi.logout(refreshToken);

Méthodes utilisateurs

Avant :

const users = await apiService.getUsers({ page: 1, limit: 20 });
const user = await apiService.getUser(id);
const user = await apiService.getUserByUsername(username);
await apiService.updateUser(id, data);

Après :

const { data: users } = await apiClient.get('/users', { params: { page: 1, limit: 20 } });
const { data: user } = await apiClient.get(`/users/${id}`);
const { data: user } = await apiClient.get(`/users/by-username/${username}`);
await apiClient.put(`/users/${id}`, data);

Méthodes tracks

Avant :

const tracks = await apiService.getTracks({ page: 1, limit: 20 });
const track = await apiService.getTrack(id);
await apiService.uploadTrack(file, metadata);
await apiService.deleteTrack(id);

Après :

import { trackApi } from '@/features/tracks/api/trackApi';

const { data: tracks } = await apiClient.get('/tracks', { params: { page: 1, limit: 20 } });
const { data: track } = await apiClient.get(`/tracks/${id}`);
await trackApi.uploadTrack(file, metadata);
await apiClient.delete(`/tracks/${id}`);

Méthodes conversations

Avant :

const conversations = await apiService.getConversations();
const conversation = await apiService.getConversation(id);
await apiService.addMemberToConversation(id, userId);
const { messages } = await apiService.getConversationHistory(id, { limit: 50 });

Après :

const { data: conversations } = await apiClient.get('/conversations');
const { data: conversation } = await apiClient.get(`/conversations/${id}`);
await apiClient.post(`/conversations/${id}/members`, { user_id: userId });
const { data } = await apiClient.get(`/conversations/${id}/history`, { params: { limit: 50 } });
const messages = data.messages || [];

Méthodes messages

Avant :

const messages = await apiService.getMessages(conversationId, { page: 1, limit: 50 });
await apiService.sendMessage(conversationId, content, parentMessageId);

Après :

const { data: messages } = await apiClient.get('/messages', {
  params: { conversation_id: conversationId, page: 1, limit: 50 }
});
await apiClient.post('/messages', {
  conversation_id: conversationId,
  content,
  parent_message_id: parentMessageId
});

Méthodes sessions

Avant :

await apiService.logoutSession();
await apiService.logoutAllSessions();
const sessions = await apiService.getSessions();
await apiService.revokeSession(sessionId);
const stats = await apiService.getSessionStats();
await apiService.refreshSession();

Après :

await apiClient.post('/sessions/logout');
await apiClient.post('/sessions/logout-all');
const { data: sessions } = await apiClient.get('/sessions');
await apiClient.delete(`/sessions/${sessionId}`);
const { data: stats } = await apiClient.get('/sessions/stats');
await apiClient.post('/sessions/refresh');

Notes importantes

1. Format de réponse : apiClient unwrap automatiquement le format { success: true, data: {...} } du backend, donc response.data contient directement les données.

2. Gestion d'erreurs : apiClient utilise parseApiError pour standardiser les erreurs. Les erreurs sont automatiquement parsées en ApiError.

3. Refresh token : apiClient gère automatiquement le refresh du token en cas de 401, pas besoin de le faire manuellement.

4. Types : Utilisez les types TypeScript appropriés pour les réponses :

   const { data: user } = await apiClient.get<User>('/users/123');
   

Fichiers à migrer

• apps/web/src/stores/library.ts
• apps/web/src/features/library/components/LibraryManager.tsx
• apps/web/src/features/user/components/ProfileForm.tsx
• apps/web/src/stores/chat.ts
• apps/web/src/features/chat/components/VirtualizedChatMessages.tsx
• apps/web/src/features/chat/components/ChatInterface.tsx
• apps/web/src/features/library/components/UploadModal.tsx

Timeline

• Phase 1 (Maintenant) : ApiService est marqué comme deprecated avec warnings
• Phase 2 (Prochaine release) : Migration progressive des fichiers listés ci-dessus
• Phase 3 (Version future) : Suppression complète de ApiService