igny8/unified-api/sample -singel-doc-for-6-sections.md

Understood. Here is the complete consolidated master document, combining all 6 sections into a single, clean, unified API Standard for IGNY8. No questions. No fragmentation. This becomes the single source of truth for backend, frontend, plugin, and 3rd-party integration.

---

IGNY8 API STANDARDIZATION – MASTER CONSOLIDATED DOCUMENT

Version: 1.0 Purpose: Establish a single unified API contract for the IGNY8 platform (app, plugin, and external API consumers). Applies To:

• Django backend
• React frontend
• WordPress plugin
• 3rd-party API consumers
• Internal automations / CRON / AI functions

---

1. API Versioning & Structure

Base URL:

/api/v1/

Module Namespaces:

auth/
planner/
writer/
system/
billing/

All current and future endpoints must follow predictable REST patterns under these namespaces.

Versioning Rules:

• v1 remains stable long-term
• Breaking changes require v2
• Deprecations allowed only with explicit timeline

---

2. Authentication Standard (Unified)

Primary method: JWT Bearer token

Authorization: Bearer <access_token>

Fallbacks:

• Session auth (admin panel)
• Basic auth (debug/testing)

Token Guarantees:

• Contains user_id and account_id
• Resolves account → tenant context automatically
• Sets request.account in all ViewSets

Public endpoints allowed:

• register
• login
• plans
• industries
• system/status

Everything else requires JWT.

---

3. Authorization & Permissions Standard

Every endpoint must use consistent layered authorization:

Base layers:

1. User must be authenticated
2. User must belong to the tenant/account
3. User must have appropriate role
4. User must have access to requested site/sector

Role hierarchy:

owner > admin > editor > viewer > system_bot

Standard permission classes:

• IsAuthenticatedAndActive
• HasTenantAccess
• IsViewerOrAbove (read-only)
• IsEditorOrAbove (content operations)
• IsAdminOrOwner (settings, keys, billing)

All ViewSets must explicitly declare the correct class.

---

4. Unified Response Format (Mandatory)

This is the global standard for all endpoints, no exception.

Success

{
  "success": true,
  "data": {},
  "message": "Optional readable message"
}

Error

{
  "success": false,
  "error": "Readable top-level message",
  "errors": { "field": ["details"] },
  "request_id": "uuid"
}

Paginated

{
  "success": true,
  "count": 120,
  "next": "...",
  "previous": "...",
  "results": [...],
  "message": "Optional"
}

This single structure is used across:

• App
• Plugin
• External API clients
• AI pipeline
• CRON jobs

---

5. Unified Error Handling (Global Standard)

Centralized exception handler requirements:

• Wrap all errors in unified format
• Use proper status codes (400, 401, 403, 404, 409, 422, 500)
• Include sanitised validation errors under errors
• Always attach request_id
• Log full exception details
• In DEBUG mode: include traceback + request context

Server-side Logging

• All 4xx logs as warning
• All 5xx logs as error
• Use structured format
• Store in rotating log files
• Provide hooks for Sentry in production

---

6. Unified Request Payload Rules

All endpoints must follow:

• snake_case field names
• predictable field groups
• standardized pagination params
• standardized filters
• standardized bulk update patterns
• standardized action payloads
• standardized error messages

Bulk actions:

{ "ids": [1,2,3], ... }

Filtering:

?search=  
?status=  
?site_id=  
?sector_id=

---

7. Tenant / Site / Sector Scoping Rules

Every resource created or fetched must be scoped by:

1. Account/Tenant
2. Site
3. Sector

Enforcement:

• AccountModelViewSet handles account isolation
• SiteSectorModelViewSet filters queries by site/sector
• All custom actions must also use .get_queryset() to avoid bypassing filters
• Any ID list must be verified to belong to the authenticated tenant

---

8. Module-Wise API Rules (Planner / Writer / System / Billing)

Planner Module

Covers keywords → clusters → ideas.

Rules:

• All endpoints require authentication
• Auto-cluster limited to 20 keywords/request
• Ideas generation limited to 1 cluster/request
• Standardized payloads for imports/exports
• Bulk actions must validate tenant ownership

---

Writer Module

Covers tasks → content → image prompts → images.

Rules:

• 1 AI content generation per task
• 1 image generation per request
• Bulk actions max 50
• Image prompt extraction uses unified response
• Must align with progress tracking

---

System Module

Covers prompts, strategies, profiles, integrations, task progress.

Rules:

• Saving prompts requires editor/admin
• Integration settings require admin/owner
• All tests (OpenAI/Runware) return unified format
• Progress endpoint returns stable JSON for progress modal

---

Billing Module

Covers credit balance, usage logs, transactions.

Rules:

• Balance/usage require authenticated tenant
• Transactions require admin/owner
• Unified reporting structure
• No raw model data returned

---

9. API Governance, Rate Limits, and Safety Controls

Soft limits

• 50 tasks per bulk action
• 20 keywords per cluster batch
• 1 cluster → ideas generation
• 1 content → image prompt extraction
• 1 image generation per job
• Per-tenant throttling (future)

Safety checks

• Validate all IDs belong to tenant
• Validate dependent records exist
• Reject oversized payloads
• Reject invalid site/sector assignments
• Reject stale/wrong tenant tokens

---

10. Logging, Monitoring, and Diagnostics

Backend logging

• timestamp
• request_id
• endpoint
• user_id
• account_id
• status_code
• error_message
• traceback for 5xx

Frontend Debug Panel Integration

All responses must support:

• request ID
• readable error messages
• consistent progress steps
• error visibility in real time

---

11. Progress Modal Standard (AI Functions)

All AI functions must output uniform progress metadata:

Steps example for image prompt extraction

Smart Image Prompts
Checking content and image slots
Mapping Content for X Image Prompts
Writing Featured Image Prompts
Writing X In-article Image Prompts
Assigning Prompts to Slots

Success message:

Featured Image and X In-article Image Prompts ready for image generation

All four AI functions must follow identical UI messaging structure.

---

12. Standard Frontend/Plugin Integration Rules

Frontend

• All responses parsed through the unified envelope
• 401 triggers logout → redirect to login
• 403 triggers permission alert
• Errors read from .error or .errors
• Pagination reads .results

WordPress Plugin

• Uses the same JWT flow
• No custom plugin-specific endpoints
• Uses the app’s /api/v1/ fully
• WP only handles mapping + meta assignment

3rd-Party APIs

• Full compatibility with unified format
• Full access where tenant/permissions allow
• No special handling needed

---

13. Refactor & Migration Plan (One-Time Update)

1. Introduce unified response wrapper
2. Replace all custom responses in ViewSets
3. Inject consistent permission classes
4. Wrap all exceptions with centralized handler
5. Update serializers to rely on unified errors
6. Patch all custom actions to validate payloads
7. Update app’s frontend API client
8. Remove deprecated endpoint patterns
9. Regenerate Postman/OpenAPI schema
10. Update WordPress plugin integration
11. Run full-suite regression tests

This whole migration becomes the Phase-4 API refactor inside the IGNY8 full migration pipeline.

---

14. Success Criteria

• Every endpoint returns same envelope
• All errors fully unified
• No endpoint leaks raw DRF format
• No inconsistent auth behavior
• No inconsistent pagination
• No inconsistent validation errors
• Plugin works using same exact API
• Third-party clients can implement without special rules
• Frontend debug panel reads everything correctly
• CRON + automations structured identically

---

15. Final Notes

This consolidated document replaces all six API planning files. It is now the single standard for:

• Backend implementation
• Frontend integration
• Plugin development
• External API docs
• AI function progress UI
• DevOps & monitoring