API-MIGRATION-GUIDE.md

# API Migration Guide: Moving to Centralized Axios Implementation

## Why Migrate?

Our project has implemented a new centralized API client using Axios interceptors which provides:

- **Centralized error handling**: Errors are handled consistently across all API calls
- **Standardized response format**: All API responses follow the same format
- **Authentication**: Automatic token management
- **Retries and token refresh**: Automatic token refresh for expired tokens
- **Progress tracking**: Built-in progress tracking for file uploads
- **Reduced code duplication**: No need to repeat the same error handling everywhere
- **Easier debugging**: All API requests go through the same pipeline, making it easier to debug

## Migration Steps

### 1. Update Imports

Replace direct Axios imports with our utility functions:

```typescript
// OLD
import axios from 'axios';
import { API_BASE_URL } from '../config';

// NEW
import { get, getList, post, put, patch, del, uploadFile } from '../lib/api/api-utils';
```

### 2. Remove API_BASE_URL from Service URLs

The base URL is already configured in the Axios instance, so you should:

```typescript
// OLD
private baseUrl = `${API_BASE_URL}/api/users`;

// NEW
private baseUrl = `/api/users`;
```

### 3. Replace Direct Axios Calls

Replace direct Axios calls with our utility functions:

#### GET Requests

```typescript
// OLD
async getItem(id: number): Promise<ResponseData<Item>> {
  try {
    const response = await axios.get(`${this.baseUrl}/${id}`);
    return {
      data: response.data,
      success: true,
      message: 'Item fetched successfully'
    };
  } catch (error: any) {
    return {
      data: {} as Item,
      success: false,
      message: error.message || 'Failed to fetch item'
    };
  }
}

// NEW
async getItem(id: number): Promise<ResponseData<Item>> {
  return get<Item>(`${this.baseUrl}/${id}`);
}
```

#### GET List Requests

```typescript
// OLD
async getItems(): Promise<ResponseData<Item[]>> {
  try {
    const response = await axios.get(this.baseUrl);
    return {
      data: response.data,
      success: true,
      message: 'Items fetched successfully'
    };
  } catch (error: any) {
    return {
      data: [],
      success: false,
      message: error.message || 'Failed to fetch items'
    };
  }
}

// NEW
async getItems(): Promise<ResponseData<Item[]>> {
  return getList<Item>(this.baseUrl);
}
```

#### POST Requests

```typescript
// OLD
async createItem(item: ItemCreateRequest): Promise<ResponseData<Item>> {
  try {
    const response = await axios.post(this.baseUrl, item, {
      headers: { 'Content-Type': 'application/json' }
    });
    return {
      data: response.data,
      success: true,
      message: 'Item created successfully'
    };
  } catch (error: any) {
    return {
      data: {} as Item,
      success: false,
      message: error.message || 'Failed to create item'
    };
  }
}

// NEW
async createItem(item: ItemCreateRequest): Promise<ResponseData<Item>> {
  return post<Item, ItemCreateRequest>(this.baseUrl, item);
}
```

#### PUT Requests

```typescript
// OLD
async updateItem(item: ItemUpdateRequest): Promise<ResponseData<Item>> {
  try {
    const response = await axios.put(`${this.baseUrl}/${item.id}`, item, {
      headers: { 'Content-Type': 'application/json' }
    });
    return {
      data: response.data,
      success: true,
      message: 'Item updated successfully'
    };
  } catch (error: any) {
    return {
      data: {} as Item,
      success: false,
      message: error.message || 'Failed to update item'
    };
  }
}

// NEW
async updateItem(item: ItemUpdateRequest): Promise<ResponseData<Item>> {
  return put<Item, ItemUpdateRequest>(`${this.baseUrl}/${item.id}`, item);
}
```

#### DELETE Requests

```typescript
// OLD
async deleteItem(id: number): Promise<ResponseData<boolean>> {
  try {
    await axios.delete(`${this.baseUrl}/${id}`);
    return {
      data: true,
      success: true,
      message: 'Item deleted successfully'
    };
  } catch (error: any) {
    return {
      data: false,
      success: false,
      message: error.message || 'Failed to delete item'
    };
  }
}

// NEW
async deleteItem(id: number): Promise<ResponseData<boolean>> {
  return del(`${this.baseUrl}/${id}`);
}
```

#### File Uploads

```typescript
// OLD
async uploadFile(file: File, metadata: any): Promise<ResponseData<Document>> {
  try {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('metadata', JSON.stringify(metadata));
    
    const response = await axios.post(`${this.baseUrl}/upload`, formData, {
      headers: { 'Content-Type': 'multipart/form-data' },
      onUploadProgress: (progressEvent) => {
        // Handle progress
      }
    });
    
    return {
      data: response.data,
      success: true,
      message: 'File uploaded successfully'
    };
  } catch (error: any) {
    return {
      data: {} as Document,
      success: false,
      message: error.message || 'Failed to upload file'
    };
  }
}

// NEW
async uploadDocument(file: File, metadata: any): Promise<ResponseData<Document>> {
  return uploadFile<Document>(
    `${this.baseUrl}/upload`, 
    file, 
    { metadata: JSON.stringify(metadata) },
    (progress) => {
      // Handle progress
      console.log(`Upload progress: ${progress}%`);
    }
  );
}
```

## Testing Your Migration

1. Ensure you have migrated all API calls in a service
2. Test the functionality to verify it works as expected
3. Confirm that authentication, error handling, and response formatting work correctly

## Need Help?

If you have any questions about the migration process, please refer to the full documentation in `src/lib/api/README.md` or contact the development team.