420 lines
8.3 KiB
Markdown
420 lines
8.3 KiB
Markdown
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
|