67 lines
4.0 KiB
Markdown
67 lines
4.0 KiB
Markdown
# Integration Endpoints
|
|
|
|
## Purpose
|
|
Document integration API endpoints for managing site integrations, testing connections, syncing, and handling WordPress webhooks.
|
|
|
|
## Code Locations (exact paths)
|
|
- Routing: `backend/igny8_core/modules/integration/urls.py`
|
|
- Views: `backend/igny8_core/modules/integration/views.py`
|
|
- Webhooks: `backend/igny8_core/modules/integration/webhooks.py`
|
|
- Services: `backend/igny8_core/business/integration/services/*`
|
|
|
|
## High-Level Responsibilities
|
|
- CRUD for `SiteIntegration` records.
|
|
- Test connections (detail and collection-level), trigger syncs, fetch sync status, update site structure, and sync WordPress content.
|
|
- Expose WordPress webhook endpoints for status/metadata updates.
|
|
|
|
## Detailed Behavior
|
|
- Base path: `/api/v1/integration/`
|
|
- Viewset: `IntegrationViewSet` (`/integrations/`, inherits `SiteSectorModelViewSet` but overrides queryset to filter by site_id since integrations have site only).
|
|
- Permissions: `IsAuthenticatedAndActive`, `IsEditorOrAbove`; throttle scope `integration`.
|
|
- Serializer exposes derived `api_key` (from credentials) and validates WordPress integrations require API key.
|
|
- Actions:
|
|
- `test_connection` (detail): calls `IntegrationService.test_connection` on existing integration; returns success/error.
|
|
- `test_connection_collection` (POST `integrations/test-connection/`, AllowAny): accepts site_id/api_key/site_url; validates site ownership or matching `Site.wp_api_key`; creates integration if missing; tests WordPress connection; deletes integration on failure; returns integration_id on success.
|
|
- `sync`: triggers `SyncService.sync` (direction metadata/both/to_external/from_external); metadata-only path uses `SyncMetadataService` internally.
|
|
- `sync_status`: returns sync status from `SyncService`.
|
|
- `update_site_structure`: updates `config_json.content_types` (post_types/taxonomies, plugin flags, timestamp) from WordPress push payload.
|
|
- `get_content_types`: returns content type config from integration config.
|
|
- `debug_status`: returns debug data via `SyncHealthService`.
|
|
- `sync_wordpress_content`: calls `ContentSyncService.sync_from_wordpress` for a specific content_id.
|
|
- Webhooks:
|
|
- `/webhooks/wordpress/status/` and `/webhooks/wordpress/metadata/` endpoints for WordPress callbacks (handled in `webhooks.py`).
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- `SiteIntegration`, `SyncEvent`, `Site`, `Account`.
|
|
|
|
## Execution Flow
|
|
- CRUD/test/sync requests → DRF auth → site-filtered queryset → service calls → model updates/sync actions. Collection-level test may create/delete integration based on result. Webhooks call handlers for incoming WordPress events.
|
|
|
|
## Cross-Module Interactions
|
|
- Integrations used by publishing/sync flows to external platforms; WordPress API key path relies on `Site.wp_api_key` and integration credentials.
|
|
- Sync services interact with writer/planner content for metadata/content sync.
|
|
|
|
## State Transitions
|
|
- Integration `sync_status/last_sync_at/is_active/sync_enabled` updated by sync/test actions; `SyncEvent` records per-action success/failure with timestamps and IDs.
|
|
|
|
## Error Handling
|
|
- Invalid site/auth/API key return 403/404/400; unsupported platforms raise `NotImplementedError`; failed collection-level tests delete newly created integrations.
|
|
|
|
## Tenancy Rules
|
|
- All endpoints scoped to the site/account; queryset filters by site_id and permissions enforce authenticated editor-or-above unless using collection-level API key path.
|
|
|
|
## Billing Rules
|
|
- None; integration endpoints do not change credits.
|
|
|
|
## Background Tasks / Schedulers
|
|
- None specific; sync logic executes in service calls (may delegate internally).
|
|
|
|
## Key Design Considerations
|
|
- Single integration per site+platform; collection-level test supports plugin onboarding with API key.
|
|
- Credentials stored as JSON (encryption pending).
|
|
|
|
## How Developers Should Work With This Module
|
|
- Use `IntegrationService` for CRUD/test; extend platform support via new test logic and serializer validation.
|
|
- Keep site scoping and API key validation intact for collection-level tests.
|
|
|