74 lines
4.9 KiB
Markdown
74 lines
4.9 KiB
Markdown
# REST API Reference
|
|
|
|
## Purpose
|
|
Summarize the major API groups, their base paths, and key actions as implemented in routing and viewsets.
|
|
|
|
## Code Locations (exact paths)
|
|
- Root routing: `backend/igny8_core/urls.py`
|
|
- Auth endpoints: `backend/igny8_core/auth/urls.py` (APIView + routers)
|
|
- 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: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
|
|
- Automation: `backend/igny8_core/business/automation/urls.py`
|
|
- Integration: `backend/igny8_core/modules/integration/urls.py`
|
|
- Linker/Optimizer/Publisher: respective `modules/*/urls.py`
|
|
|
|
## High-Level Responsibilities
|
|
- Provide RESTful CRUD endpoints for core resources (auth, planner, writer, billing, automation, integration, etc.) plus custom actions for domain workflows (automation run, billing payments, integration sync, content generation).
|
|
|
|
## Detailed Behavior (by group)
|
|
- Authentication (`/api/v1/auth/`):
|
|
- Routers: groups, users, accounts, subscriptions, site-access, plans, sites, sectors, industries, seed-keywords.
|
|
- APIViews: register, login, change password, refresh token; responses issue JWTs and session login.
|
|
- CSV admin helpers exposed separately under `/admin/igny8_core_auth/...` for industries/seed keywords.
|
|
- Account management (`/api/v1/account/`):
|
|
- Settings (`settings/` get/patch), team (`team/` list/create, `team/<id>/` delete), usage analytics (`usage/analytics/`).
|
|
- Planner (`/api/v1/planner/`):
|
|
- `keywords/`, `clusters/`, `ideas/` (CRUD, filtering/search/ordering, bulk delete/update, bulk add from seed).
|
|
- Writer (`/api/v1/writer/`):
|
|
- `tasks/`, `images/`, `content/`, `taxonomies/` (CRUD, filtering/search/ordering).
|
|
- Custom actions: `tasks/auto_generate_content` (AI generation), `tasks/bulk_*`, `images/file`, grouped image utilities; content/taxonomy helpers in viewset.
|
|
- System (`/api/v1/system/`): system settings, prompts, author profiles, etc. (see module docs).
|
|
- Billing (`/api/v1/billing/`):
|
|
- Invoices (`invoices/`, detail, `download_pdf`), payments (`payments/`, `available_methods`, manual payment), credit packages (`credit-packages/`, purchase), transactions (`transactions/`), payment methods (`payment-methods/`, `set_default`), credits (`credits/balance`, `credits/usage`, `credits/transactions`).
|
|
- Admin billing under `/api/v1/admin/` (see module billing admin URLs).
|
|
- Automation (`/api/v1/automation/`):
|
|
- Config (`config`, `update_config`), run (`run_now`), current run, history, logs, estimate, pipeline_overview, current_processing, pause/resume/cancel.
|
|
- Integration (`/api/v1/integration/`):
|
|
- `integrations/` CRUD, `test_connection`, collection-level `test-connection`, `sync`, `sync_status`, `update-structure`, `get_content_types`, `debug_status`, `sync_wordpress_content`.
|
|
- Webhooks: `/webhooks/wordpress/status/`, `/webhooks/wordpress/metadata/`.
|
|
- Linker/Optimizer/Publisher: endpoints under `/api/v1/linker/`, `/api/v1/optimizer/`, `/api/v1/publisher/` (viewsets for respective domain resources; see module docs).
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- Auth/account models, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images/Taxonomy), billing models (invoices/payments/credits), automation models (runs/configs), integration models (SiteIntegration/SyncEvent), and other module models as routed above.
|
|
|
|
## Execution Flow
|
|
- Requests hit module routers; viewsets/actions enforce permissions, throttles, and tenancy; serializers map models; responses use unified format.
|
|
|
|
## Cross-Module Interactions
|
|
- Auth JWTs used by all modules.
|
|
- Billing credits checked in writer/automation flows; billing endpoints expose balances/usage.
|
|
- Integration and publishing rely on writer content; automation depends on planner/writer data.
|
|
|
|
## State Transitions
|
|
- Managed by respective viewsets (e.g., task status, automation status, invoice/payment status).
|
|
|
|
## Error Handling
|
|
- Unified error responses; 4xx/5xx codes per viewset logic; throttling per scope.
|
|
|
|
## Tenancy Rules
|
|
- Base viewsets enforce account/site/sector filtering; API key auth supports WordPress paths; admin/developer/system roles may bypass filters as coded in base viewsets/auth middleware.
|
|
|
|
## Billing Rules
|
|
- Credits enforced in writer/automation service calls; billing endpoints expose ledger/usage/balance; insufficient credits return 402 where applicable.
|
|
|
|
## Background Tasks / Schedulers
|
|
- Automation actions enqueue Celery runs; writer content generation may enqueue AI tasks; other modules mostly synchronous.
|
|
|
|
## Key Design Considerations
|
|
- Consistent `/api/v1/` namespace with per-module routers.
|
|
- OpenAPI schema available at `/api/schema`, Swagger at `/api/docs`, Redoc at `/api/redoc`.
|
|
- Use module docs for endpoint-level details; this file outlines the map of API groups and actions.
|