igny8/master-docs/20-api/API-OVERVIEW.md

API Overview

Purpose

Describe the overall API surface, routing, authentication, pagination, throttling, and response format implemented in the backend.

Code Locations (exact paths)

• Root routing: backend/igny8_core/urls.py
• Module routers:
  • Auth: backend/igny8_core/auth/urls.py
  • Account management: backend/igny8_core/api/urls.py
  • Planner: backend/igny8_core/modules/planner/urls.py
  • Writer: backend/igny8_core/modules/writer/urls.py
  • System: backend/igny8_core/modules/system/urls.py
  • Billing (full): backend/igny8_core/business/billing/urls.py
  • Billing admin: backend/igny8_core/modules/billing/admin_urls.py
  • Automation: backend/igny8_core/business/automation/urls.py
  • Linker: backend/igny8_core/modules/linker/urls.py
  • Optimizer: backend/igny8_core/modules/optimizer/urls.py
  • Publisher: backend/igny8_core/modules/publisher/urls.py
  • Integration: backend/igny8_core/modules/integration/urls.py
• DRF settings: backend/igny8_core/settings.py (REST_FRAMEWORK config)
• Base viewsets/responses: backend/igny8_core/api/base.py, backend/igny8_core/api/response.py

High-Level Responsibilities

• Expose REST endpoints under /api/v1/* for auth, account/team, planner, writer, system, billing, automation, linker, optimizer, publisher, and integration.
• Enforce unified response format, tenant scoping, authentication (API key/JWT/session/basic), and scoped throttling.
• Provide OpenAPI schema and interactive docs at /api/schema, /api/docs, /api/redoc.

Detailed Behavior

• Routing (root): /api/v1/auth/, /api/v1/account/, /api/v1/planner/, /api/v1/writer/, /api/v1/system/, /api/v1/billing/, /api/v1/admin/ (billing admin), /api/v1/automation/, /api/v1/linker/, /api/v1/optimizer/, /api/v1/publisher/, /api/v1/integration/. Admin + CSV helpers mounted under /admin/.
• Auth stack (settings REST_FRAMEWORK):
  • APIKeyAuthentication (WordPress bridge, sets request.account/site when Bearer token is not JWT-like).
  • JWTAuthentication (Bearer JWT access tokens).
  • CSRFExemptSessionAuthentication (session without CSRF for API).
  • Basic auth fallback.
• Permissions default AllowAny in settings; individual viewsets specify stricter permissions (e.g., IsAuthenticatedAndActive, role checks).
• Tenancy: AccountContextMiddleware sets request.account; base viewsets (AccountModelViewSet, SiteSectorModelViewSet) auto-filter querysets by account/site/sector and set account on create.
• Pagination: CustomPageNumberPagination (page/ page_size; defaults in settings).
• Filtering/search/ordering: enabled globally via DRF filter backends; viewsets declare fields and search options.
• Throttling: DebugScopedRateThrottle with scope keys defined in settings for auth, planner, writer, billing, automation, etc.; bypassed when IGNY8_DEBUG_THROTTLE true.
• Responses: success/error helpers wrap payloads with success, data/error, optional errors, and request_id.
• OpenAPI: drf-spectacular configured with tags, schema routes; interactive docs at /api/docs (Swagger UI) and /api/redoc.

Data Structures / Models Involved (no code)

• See module-specific docs; API layer uses serializers tied to planner/writer/billing/auth/etc. models.

Execution Flow

• Request → middleware (request ID, account context, resource tracking) → DRF auth (API key/JWT/session) → viewset/action → serializer validation → model ops → unified response. Pagination/filtering/search applied where configured.

Cross-Module Interactions

• Auth endpoints issue JWTs consumed by all other modules.
• Tenancy middleware/context is shared across all module viewsets.
• Billing credits enforced in content/automation flows via service calls, surfaced through billing endpoints.

State Transitions

• Handled in module viewsets (e.g., task status changes, run statuses); API layer mediates CRUD and custom actions.

Error Handling

• Custom exception handler (enabled by default) wraps errors in unified format.
• Viewsets return structured 400/401/403/404/500 responses; throttling returns standard DRF throttle responses.

Tenancy Rules

• Account/site/sector scoping enforced by middleware + base viewsets; admin/developer/system roles may bypass filters at the viewset layer per role helpers.

Billing Rules

• Credit checks occur in service calls (content generation, automation); billing endpoints report balances/usage/limits. Some endpoints return 402 on insufficient credits.

Background Tasks / Schedulers

• Automation and some AI flows run via Celery; API endpoints trigger tasks (e.g., automation run_now, writer auto_generate_content).

Key Design Considerations

• Consistent routing under /api/v1/ with module-specific routers.
• Unified responses and throttling scopes to keep client behavior consistent.
• OpenAPI docs generated from viewset/serializer annotations for discoverability.

How Developers Should Work With This Module

• Mount new modules under /api/v1/<module>/ in igny8_core/urls.py.
• Inherit from base viewsets to get scoping/unified responses; declare permissions, filters, and throttles per viewset.
• Annotate endpoints with drf-spectacular for accurate schema; keep success/error responses consistent via helpers.