Files

IGNY8 VPS (Salman) 069e0a24d8 Remove comprehensive API endpoints analysis document from the repository. This file contained detailed information on request/response formats, authentication methods, and endpoint statistics.

2025-11-14 14:48:48 +00:00

33 KiB

Raw Blame History

API Implementation Plan - Section 5: Refactor Endpoints Module by Module

Date: 2025-01-XX
Status: Planning
Priority: High
Related Documents: API-ENDPOINTS-ANALYSIS.md, API-IMPLEMENTATION-PLAN-SECTION1.md, API-IMPLEMENTATION-PLAN-SECTION2.md, API-IMPLEMENTATION-PLAN-SECTION3.md, API-IMPLEMENTATION-PLAN-SECTION4.md

Executive Summary

This document outlines the implementation plan for Section 5: Refactor Endpoints Module by Module across the IGNY8 API layer. The goal is to systematically upgrade all API endpoints across all modules (Auth, Planner, Writer, System, Billing) to follow the unified interface design established in Sections 1-4, without breaking existing frontend functionality.

Key Objectives:

Create refactor checklist template for tracking progress
Refactor one module at a time, starting with least dependent modules
Preserve backward compatibility where needed
Comprehensive testing before global deployment
Update documentation with refactored endpoint status

Note: This section consolidates and applies all previous sections (1-4) to actual endpoint refactoring.

Current State Analysis
Implementation Tasks
Task 1: Create Refactor Checklist Template
Task 2: Refactor One Module at a Time
Task 3: Track Affected Files in Git Commit Notes
Task 4: Preserve Backward Compatibility
Task 5: Final Round of Testing Before Global Deployment
Task 6: Documentation Update
Task 7: Changelog Entry
Testing Strategy
Rollout Plan
Success Criteria

Current State Analysis

Current Endpoint Status

Based on API-ENDPOINTS-ANALYSIS.md:

Total Endpoints: 100+ endpoints across 5 modules
Current State:
- Mixed response formats (Section 1 to fix)
- Inconsistent permissions (Section 2 to fix)
- Inconsistent error handling (Section 3 to fix)
- No rate limiting (Section 4 to fix)
Module Dependencies:
- System Module: Least dependent, good starting point
- Billing Module: Independent, good for early refactoring
- Planner Module: Depends on Auth, moderate dependency
- Writer Module: Depends on Planner, higher dependency
- Auth Module: Core dependency, refactor last or carefully
Frontend Integration:
- Frontend uses these endpoints extensively
- Breaking changes would impact user experience
- Need careful testing and backward compatibility

Implementation Tasks

Overview

Task ID	Task Name	Priority	Estimated Effort	Dependencies
1.1	Create refactor checklist template	High	2 hours	None
2.1	Refactor System module	High	12 hours	Sections 1-4
2.2	Refactor Billing module	High	8 hours	Sections 1-4
2.3	Refactor Planner module	High	16 hours	Sections 1-4
2.4	Refactor Writer module	High	16 hours	Sections 1-4
2.5	Refactor Auth module	High	12 hours	Sections 1-4
3.1	Set up Git tracking	Medium	2 hours	None
4.1	Implement legacy format support (if needed)	Low	6 hours	2.1-2.5
5.1	Frontend integration testing	High	12 hours	2.1-2.5
5.2	Regression testing	High	8 hours	2.1-2.5
6.1	Update documentation	High	6 hours	2.1-2.5
7.1	Create changelog entry	Low	1 hour	All tasks

Total Estimated Effort: ~101 hours (~2.5 weeks)

Task 1: Create Refactor Checklist Template

Goal

Create a comprehensive checklist template to track refactoring progress for each endpoint.

Implementation Steps

Step 1.1: Create Checklist Document

File: docs/API-REFACTOR-CHECKLIST.md

Implementation:

# API Refactor Checklist

This document tracks the refactoring progress of all API endpoints to follow the unified interface design.

## Checklist Legend

- ✅ Complete
- ⏳ In Progress
- ❌ Not Started
- ⚠️ Issues Found
- 🔄 Needs Review

## Refactoring Criteria

Each endpoint must meet all of the following:

1. **Response Format:** ✅ Uses `success_response()` or `error_response()`
2. **Error Format:** ✅ Uses unified error format with `error` and `errors` fields
3. **Permissions:** ✅ Uses appropriate permission classes (Section 2)
4. **Throttle Scope:** ✅ Has explicit `throttle_scope` assignment (Section 4)
5. **Exception Handling:** ✅ Errors handled by centralized exception handler (Section 3)
6. **Tested with Frontend:** ✅ Verified working with existing frontend code
7. **Documentation:** ✅ Updated in API documentation

---

## System Module

### AI Prompt Management

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List prompts | GET | `/api/v1/system/prompts/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create prompt | POST | `/api/v1/system/prompts/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get prompt | GET | `/api/v1/system/prompts/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update prompt | PUT | `/api/v1/system/prompts/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete prompt | DELETE | `/api/v1/system/prompts/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Save prompt | POST | `/api/v1/system/prompts/save/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Reset prompt | POST | `/api/v1/system/prompts/reset/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get by type | GET | `/api/v1/system/prompts/by_type/{type}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### Integration Settings

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| Get settings | GET | `/api/v1/system/settings/integrations/{pk}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Save settings | POST | `/api/v1/system/settings/integrations/{pk}/save/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Test connection | POST | `/api/v1/system/settings/integrations/{pk}/test/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Generate test | POST | `/api/v1/system/settings/integrations/{pk}/generate/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### Author Profiles

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List profiles | GET | `/api/v1/system/author-profiles/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create profile | POST | `/api/v1/system/author-profiles/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get profile | GET | `/api/v1/system/author-profiles/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update profile | PUT | `/api/v1/system/author-profiles/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete profile | DELETE | `/api/v1/system/author-profiles/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

---

## Billing Module

### Credit Balance

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| Get balance | GET | `/api/v1/billing/credits/balance/balance/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### Credit Usage

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List usage | GET | `/api/v1/billing/credits/usage/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get usage | GET | `/api/v1/billing/credits/usage/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Usage summary | GET | `/api/v1/billing/credits/usage/summary/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Usage limits | GET | `/api/v1/billing/credits/usage/limits/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### Credit Transactions

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List transactions | GET | `/api/v1/billing/credits/transactions/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get transaction | GET | `/api/v1/billing/credits/transactions/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

---

## Planner Module

### Keywords

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List keywords | GET | `/api/v1/planner/keywords/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create keyword | POST | `/api/v1/planner/keywords/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get keyword | GET | `/api/v1/planner/keywords/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update keyword | PUT | `/api/v1/planner/keywords/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete keyword | DELETE | `/api/v1/planner/keywords/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Bulk delete | POST | `/api/v1/planner/keywords/bulk_delete/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Bulk update status | POST | `/api/v1/planner/keywords/bulk_update_status/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Auto cluster | POST | `/api/v1/planner/keywords/auto_cluster/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Export keywords | GET | `/api/v1/planner/keywords/export/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Import keywords | POST | `/api/v1/planner/keywords/import_keywords/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### Clusters

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List clusters | GET | `/api/v1/planner/clusters/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create cluster | POST | `/api/v1/planner/clusters/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get cluster | GET | `/api/v1/planner/clusters/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update cluster | PUT | `/api/v1/planner/clusters/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete cluster | DELETE | `/api/v1/planner/clusters/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Auto generate ideas | POST | `/api/v1/planner/clusters/auto_generate_ideas/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### Content Ideas

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List ideas | GET | `/api/v1/planner/ideas/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create idea | POST | `/api/v1/planner/ideas/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get idea | GET | `/api/v1/planner/ideas/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update idea | PUT | `/api/v1/planner/ideas/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete idea | DELETE | `/api/v1/planner/ideas/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Bulk queue to writer | POST | `/api/v1/planner/ideas/bulk_queue_to_writer/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

---

## Writer Module

### Tasks

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List tasks | GET | `/api/v1/writer/tasks/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create task | POST | `/api/v1/writer/tasks/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get task | GET | `/api/v1/writer/tasks/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update task | PUT | `/api/v1/writer/tasks/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete task | DELETE | `/api/v1/writer/tasks/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Auto generate content | POST | `/api/v1/writer/tasks/auto_generate_content/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### Content

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List content | GET | `/api/v1/writer/content/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create content | POST | `/api/v1/writer/content/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get content | GET | `/api/v1/writer/content/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update content | PUT | `/api/v1/writer/content/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete content | DELETE | `/api/v1/writer/content/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Generate image prompts | POST | `/api/v1/writer/content/generate_image_prompts/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### Images

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List images | GET | `/api/v1/writer/images/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create image | POST | `/api/v1/writer/images/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get image | GET | `/api/v1/writer/images/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update image | PUT | `/api/v1/writer/images/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete image | DELETE | `/api/v1/writer/images/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Generate images | POST | `/api/v1/writer/images/generate_images/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

---

## Auth Module

### Authentication

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| Register | POST | `/api/v1/auth/register/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Login | POST | `/api/v1/auth/login/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Change password | POST | `/api/v1/auth/change-password/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get current user | GET | `/api/v1/auth/me/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

### User Management

| Endpoint | Method | Path | Response Format | Error Format | Permissions | Throttle Scope | Frontend Tested | Status |
|----------|--------|------|-----------------|--------------|-------------|----------------|-----------------|--------|
| List users | GET | `/api/v1/auth/users/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Create user | POST | `/api/v1/auth/users/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Get user | GET | `/api/v1/auth/users/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Update user | PUT | `/api/v1/auth/users/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Delete user | DELETE | `/api/v1/auth/users/{id}/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Invite user | POST | `/api/v1/auth/users/invite/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |
| Activate user | POST | `/api/v1/auth/users/{id}/activate/` | ⏳ | ⏳ | ⏳ | ⏳ | ❌ | ⏳ |

---

## Progress Summary

- **Total Endpoints:** ~100+
- **Completed:** 0
- **In Progress:** 0
- **Not Started:** ~100+
- **Completion:** 0%

**Last Updated:** 2025-01-XX

Estimated Time: 2 hours

Task 2: Refactor One Module at a Time

Goal

Systematically refactor each module, applying all standards from Sections 1-4.

Refactoring Order (Least to Most Dependent)

System Module (Least dependent)
Billing Module (Independent)
Planner Module (Depends on Auth)
Writer Module (Depends on Planner)
Auth Module (Core dependency, refactor carefully)

Implementation Steps

Step 2.1: Refactor System Module

Files to Refactor:

backend/system/api/viewsets.py - AIPromptViewSet, AuthorProfileViewSet, StrategyViewSet
backend/system/api/viewsets.py - IntegrationSettingsViewSet, SystemSettingsViewSet, etc.

Refactoring Checklist for Each ViewSet:

Inherit from BaseTenantViewSet:

from igny8_core.api.viewsets import BaseTenantViewSet

class AIPromptViewSet(BaseTenantViewSet):
    # Instead of AccountModelViewSet

Add Throttle Scope:

class AIPromptViewSet(BaseTenantViewSet):
    throttle_scope = 'system'

Replace Response Calls:

# Before
return Response({"success": True, "data": ...})

# After
from igny8_core.api.response import success_response
return success_response(data=..., message="...")

Replace Error Responses:

# Before
return Response({"error": "..."}, status=400)

# After
from igny8_core.api.response import error_response
return error_response(error="...", status_code=400)

Update Custom Actions:

@action(
    detail=False,
    methods=['post'],
    permission_classes=[IsAuthenticatedAndActive, HasTenantAccess],
    throttle_scope='system_admin'  # If admin-only
)
def save(self, request):
    # Use success_response or error_response
    pass

Estimated Time: 12 hours

Step 2.2: Refactor Billing Module

Files to Refactor:

backend/billing/api/viewsets.py - CreditBalanceViewSet, CreditUsageViewSet, CreditTransactionViewSet

Similar refactoring steps as System Module.

Estimated Time: 8 hours

Step 2.3: Refactor Planner Module

Files to Refactor:

backend/planner/api/viewsets.py - KeywordViewSet, ClusterViewSet, ContentIdeasViewSet

Additional considerations:

AI functions need throttle_scope='ai_function' or throttle_scope='planner_ai'
Bulk operations need proper error handling
Export/import endpoints may need special handling

Estimated Time: 16 hours

Step 2.4: Refactor Writer Module

Files to Refactor:

backend/writer/api/viewsets.py - TasksViewSet, ContentViewSet, ImagesViewSet

Additional considerations:

AI content generation needs throttle_scope='ai_function'
Image generation needs throttle_scope='image_gen'
Content operations need throttle_scope='content_write'

Estimated Time: 16 hours

Step 2.5: Refactor Auth Module

Files to Refactor:

backend/auth/api/views.py - RegisterView, LoginView, ChangePasswordView, MeView
backend/auth/api/viewsets.py - UsersViewSet, AccountsViewSet, SiteViewSet, etc.

Special considerations:

Public endpoints (register, login) should remain AllowAny
Auth endpoints need throttle_scope='auth'
User management needs IsAdminOrOwner permissions

Estimated Time: 12 hours

Testing Each Module

After refactoring each module:

Postman Testing:
- Test all CRUD operations
- Test custom actions
- Verify response format
- Verify error format
- Check throttle headers
Frontend Testing:
- Open frontend application
- Test module-specific workflows
- Verify no breaking changes
- Check error messages display correctly
Update Checklist:
- Mark endpoints as complete in API-REFACTOR-CHECKLIST.md
- Note any issues found
- Document any special cases

Task 3: Track Affected Files in Git Commit Notes

Goal

Maintain clear Git history with well-organized commits for each module refactor.

Implementation Steps

Step 3.1: Set Up Git Tracking

Commit Message Format:

chore(api): standardize [module] endpoints

- Refactor [ViewSet] to use BaseTenantViewSet
- Add throttle_scope assignments
- Replace Response() with success_response()/error_response()
- Update permissions to use standardized classes
- Update custom actions with explicit permissions

Affected endpoints:
- GET/POST/PUT/DELETE /api/v1/[module]/[resource]/
- POST /api/v1/[module]/[resource]/[action]/

Closes #[issue-number]
Ref: API-REFACTOR-CHECKLIST.md

Example Commits:

# System Module
git commit -m "chore(api): standardize system.prompts endpoints

- Refactor AIPromptViewSet to use BaseTenantViewSet
- Add throttle_scope='system'
- Replace Response() with success_response()/error_response()
- Update permissions to IsAuthenticatedAndActive + HasTenantAccess
- Update save/reset/by_type actions with explicit permissions

Affected endpoints:
- GET/POST/PUT/DELETE /api/v1/system/prompts/
- POST /api/v1/system/prompts/save/
- POST /api/v1/system/prompts/reset/
- GET /api/v1/system/prompts/by_type/{type}/

Ref: docs/API-REFACTOR-CHECKLIST.md"

# Billing Module
git commit -m "chore(api): standardize billing.credits endpoints

- Refactor CreditBalanceViewSet, CreditUsageViewSet, CreditTransactionViewSet
- Add throttle_scope='billing'
- Replace Response() with success_response()/error_response()
- Update permissions

Ref: docs/API-REFACTOR-CHECKLIST.md"

Branch Strategy:

# Create feature branch for each module
git checkout -b refactor/system-module
# ... make changes ...
git commit -m "..."
git push origin refactor/system-module

# Create PR with checklist link

Estimated Time: 2 hours (setup and documentation)

Task 4: Preserve Backward Compatibility

Goal

Ensure backward compatibility if third-party systems rely on old format.

Implementation Steps

Step 4.1: Implement Legacy Format Support (If Needed)

File: backend/igny8_core/api/response.py

Add legacy format support:

def success_response(data=None, message=None, status_code=status.HTTP_200_OK, legacy=False):
    """
    Create a standardized success response.
    
    Args:
        legacy: If True, return old format for backward compatibility
    """
    if legacy:
        # Return old format
        return Response(data, status=status_code)
    
    # Return unified format
    response_data = {
        "success": True,
        "data": data,
    }
    
    if message:
        response_data["message"] = message
    
    return Response(response_data, status=status_code)

Add Legacy Format Middleware:

File: backend/igny8_core/api/middleware.py

class LegacyFormatMiddleware(MiddlewareMixin):
    """
    Middleware that converts unified format to legacy format if ?legacy=1 is present.
    """
    
    def process_response(self, request, response):
        """
        Convert response to legacy format if legacy=1 query param is present.
        """
        if request.GET.get('legacy') == '1' and hasattr(response, 'data'):
            if isinstance(response.data, dict) and 'success' in response.data:
                # Convert unified format to legacy
                if response.data['success']:
                    # Success: return data directly
                    response.data = response.data.get('data', response.data)
                else:
                    # Error: return error field
                    response.data = {
                        'error': response.data.get('error'),
                        'errors': response.data.get('errors'),
                    }
        
        return response

Register middleware (if needed):

MIDDLEWARE = [
    # ... other middleware ...
    'igny8_core.api.middleware.LegacyFormatMiddleware',  # Only if needed
    # ... other middleware ...
]

Mark as Deprecated:

File: CHANGELOG.md

### Deprecated
- Legacy response format (use ?legacy=1 query param)
  - Will be removed in version 2.0.0
  - Migrate to unified format: `{ success, data, message, error, errors }`

Estimated Time: 6 hours (only if needed)

Task 5: Final Round of Testing Before Global Deployment

Goal

Comprehensive testing to ensure no breaking changes and all functionality works correctly.

Implementation Steps

Step 5.1: Frontend Integration Testing

Test Workflows:

Keyword → Cluster → Ideas → Tasks → Content → Images → Publish:
- Create keyword
- Create cluster
- Generate ideas
- Create task from idea
- Generate content
- Generate images
- Publish content
Settings Flow:
- Update AI prompts
- Update integration settings
- Test integration connections
- Update author profiles
Credits Flow:
- View credit balance
- View usage logs
- View usage summary
- View transactions
Auth Flow:
- Register new user
- Login
- Change password
- View current user
- Manage users (admin)

Check for:

✅ No errors in browser console
✅ All API calls return expected format
✅ Error messages display correctly
✅ Success messages display correctly
✅ Tables and dropdowns load correctly
✅ Forms submit and validate correctly
✅ Notifications work (success/failure)

Step 5.2: Regression Testing

Core Flows to Test:

Keyword Clustering:
- Create keywords
- Auto-cluster keywords
- Verify clusters created
Content Idea Generation:
- Select cluster
- Auto-generate ideas
- Verify ideas created
Task Creation:
- Queue ideas to writer
- Verify tasks created
Content Generation:
- Auto-generate content for task
- Verify content created
Image Generation:
- Generate images for content
- Verify images created
Publishing:
- Publish content (if implemented)
- Verify publishing works

Test with Multiple:

User roles (owner, admin, editor, writer, viewer)
Tenants/accounts
Plan tiers (if plan-based throttling implemented)

Step 5.3: Throttling Tests

Test Rate Limiting:

Make requests exceeding rate limits
Verify 429 responses
Verify throttle headers
Verify retry-after information
Test debug mode bypass

Estimated Time: 12 hours (frontend) + 8 hours (regression) = 20 hours

Task 6: Documentation Update

Goal

Update all documentation to reflect refactored endpoints.

Implementation Steps

Step 6.1: Update Backend Implementation Docs

File: docs/04-BACKEND-IMPLEMENTATION.md

Add Section: "Refactored Endpoints Status Table"

## Refactored Endpoints Status

All endpoints have been refactored to follow the unified interface design:

- ✅ **Response Format:** All endpoints use `success_response()` or `error_response()`
- ✅ **Error Format:** All errors use unified format with `error` and `errors` fields
- ✅ **Permissions:** All endpoints use standardized permission classes
- ✅ **Throttle Scopes:** All endpoints have explicit `throttle_scope` assignments
- ✅ **Exception Handling:** All errors handled by centralized exception handler

See [API-REFACTOR-CHECKLIST.md](../docs/API-REFACTOR-CHECKLIST.md) for detailed status of each endpoint.

Step 6.2: Link from API Endpoints Analysis

File: unified-api/API-ENDPOINTS-ANALYSIS.md

Update Response Format Standards section:

## Response Format Standards

**Status:** ✅ **Implemented** (See Section 1)

All endpoints now return unified response format. See [API-IMPLEMENTATION-PLAN-SECTION1.md](./API-IMPLEMENTATION-PLAN-SECTION1.md) for details.

For endpoint-specific status, see [API-REFACTOR-CHECKLIST.md](../docs/API-REFACTOR-CHECKLIST.md).

Step 6.3: Add Visual Diff (Optional)

File: docs/API-RESPONSE-FORMAT-DIFF.md

# API Response Format: Old vs New

## Before (Old Format)

```json
{
  "id": 1,
  "name": "Example",
  "status": "active"
}

After (New Format)

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Example",
    "status": "active"
  },
  "message": "Resource retrieved successfully"
}

Error Response: Before vs After

Before

{
  "error": "Validation failed"
}

After

{
  "success": false,
  "error": "Validation failed",
  "errors": {
    "field_name": ["Error detail"]
  },
  "request_id": "abc-123-def"
}


**Estimated Time:** 6 hours

---

## Task 7: Changelog Entry

### Goal
Document the comprehensive refactoring in the changelog.

### Implementation Steps

#### Step 7.1: Update CHANGELOG.md

**File:** `CHANGELOG.md`

**Add Entry:**
```markdown
## [1.1.0] - 2025-01-XX

### Changed
- **API Refactoring:** Refactored all major API endpoints to unified response, error, permission, and throttling design
  - All endpoints now use `BaseTenantViewSet` with standardized permissions
  - All responses use unified format: `{ success, data, message, error, errors }`
  - All errors handled by centralized exception handler
  - All endpoints have explicit `throttle_scope` assignments
  - All custom actions have explicit permission checks

### Affected Modules
- **System Module:** AIPromptViewSet, AuthorProfileViewSet, StrategyViewSet, IntegrationSettingsViewSet
- **Billing Module:** CreditBalanceViewSet, CreditUsageViewSet, CreditTransactionViewSet
- **Planner Module:** KeywordViewSet, ClusterViewSet, ContentIdeasViewSet
- **Writer Module:** TasksViewSet, ContentViewSet, ImagesViewSet
- **Auth Module:** RegisterView, LoginView, UsersViewSet, AccountsViewSet, SiteViewSet

### Migration Guide
1. **Frontend Updates:**
   - Update API client to handle unified response format
   - Check `success` field before accessing `data`
   - Use `error` field for top-level error messages
   - Use `errors` field for field-specific validation errors

2. **API Testing:**
   - All endpoints now return unified format
   - Rate limiting is enforced (see throttle headers)
   - Authentication required for most endpoints (except public ones)

3. **Backward Compatibility:**
   - Legacy format available via `?legacy=1` query param (deprecated)
   - Will be removed in version 2.0.0

### Documentation
- See [API-REFACTOR-CHECKLIST.md](../docs/API-REFACTOR-CHECKLIST.md) for endpoint status
- See [API-IMPLEMENTATION-PLAN-SECTION1.md](../unified-api/API-IMPLEMENTATION-PLAN-SECTION1.md) for response format details

Estimated Time: 1 hour

Testing Strategy

Unit Tests

Test Cases:

Each ViewSet returns unified format
Error responses use unified format
Permissions are enforced correctly
Throttle scopes are assigned correctly
Custom actions work correctly

Integration Tests

Test Cases:

End-to-end workflows (keyword → content → publish)
Error scenarios (validation, 401, 403, 429, 500)
Rate limiting enforcement
Permission enforcement
Frontend integration

Manual Testing

Checklist:

All modules refactored
All endpoints return unified format
All errors use unified format
All endpoints have proper permissions
All endpoints have throttle scopes
Frontend works correctly
No breaking changes
Documentation updated
Checklist completed

Rollout Plan

Phase 1: System & Billing (Week 1)

✅ Task 1: Create checklist
✅ Task 2.1: Refactor System module
✅ Task 2.2: Refactor Billing module
✅ Testing and validation

Phase 2: Planner & Writer (Week 2)

✅ Task 2.3: Refactor Planner module
✅ Task 2.4: Refactor Writer module
✅ Testing and validation

Phase 3: Auth & Compatibility (Week 3)

✅ Task 2.5: Refactor Auth module
✅ Task 4: Backward compatibility (if needed)
✅ Testing and validation

Phase 4: Final Testing (Week 4)

✅ Task 5: Comprehensive testing
✅ Frontend integration testing
✅ Regression testing
✅ Bug fixes

Phase 5: Documentation & Release (Week 5)

✅ Task 6: Documentation updates
✅ Task 7: Changelog entry
✅ Release to staging
✅ Production deployment

Success Criteria

Definition of Done

✅ All modules refactored
✅ All endpoints return unified format
✅ All errors use unified format
✅ All endpoints have proper permissions
✅ All endpoints have throttle scopes
✅ Frontend integration tested and working
✅ No breaking changes (or backward compatibility provided)
✅ Documentation updated
✅ Checklist completed
✅ Changelog entry created

Metrics

Coverage: 100% of endpoints refactored
Frontend Compatibility: All workflows functional
Documentation: All endpoints documented
Testing: All test scenarios pass

Risk Assessment

Risks

Breaking Changes: Frontend may break with new format
- Mitigation: Comprehensive frontend testing, backward compatibility option
Incomplete Refactoring: Some endpoints may be missed
- Mitigation: Comprehensive checklist, systematic approach
Performance Impact: New format may add overhead
- Mitigation: Minimal overhead, test performance
Timeline: Refactoring may take longer than estimated
- Mitigation: Prioritize critical endpoints, phase approach

Rollback Plan

If issues arise:

Revert specific module refactoring if needed
Use legacy format support for backward compatibility
Gradually roll back changes
Document issues for future fixes

Document Status: Implementation Plan
Last Updated: 2025-01-XX
Next Review: After Phase 1 completion

33 KiB Raw Blame History

API Implementation Plan - Section 5: Refactor Endpoints Module by Module

Executive Summary

Table of Contents

Current State Analysis

Current Endpoint Status

Implementation Tasks

Overview

Task 1: Create Refactor Checklist Template

Goal

Implementation Steps

Step 1.1: Create Checklist Document

Task 2: Refactor One Module at a Time

Goal

Refactoring Order (Least to Most Dependent)

Implementation Steps

Step 2.1: Refactor System Module

Step 2.2: Refactor Billing Module

Step 2.3: Refactor Planner Module

Step 2.4: Refactor Writer Module

Step 2.5: Refactor Auth Module

Testing Each Module

Task 3: Track Affected Files in Git Commit Notes

Goal

Implementation Steps

Step 3.1: Set Up Git Tracking

Task 4: Preserve Backward Compatibility

Goal

Implementation Steps

Step 4.1: Implement Legacy Format Support (If Needed)

Task 5: Final Round of Testing Before Global Deployment

Goal

Implementation Steps

Step 5.1: Frontend Integration Testing

Step 5.2: Regression Testing

Step 5.3: Throttling Tests

Task 6: Documentation Update

Goal

Implementation Steps

Step 6.1: Update Backend Implementation Docs

Step 6.2: Link from API Endpoints Analysis

Step 6.3: Add Visual Diff (Optional)

After (New Format)

Error Response: Before vs After

Before

After

Testing Strategy

Unit Tests

Integration Tests

Manual Testing

Rollout Plan

Phase 1: System & Billing (Week 1)

Phase 2: Planner & Writer (Week 2)

Phase 3: Auth & Compatibility (Week 3)

Phase 4: Final Testing (Week 4)

Phase 5: Documentation & Release (Week 5)

Success Criteria

Definition of Done

Metrics

Risk Assessment

Risks

Rollback Plan

33 KiB

Raw Blame History