Enhance API structure and documentation: Added new tags for Account, Integration, Automation, Linker, Optimizer, and Publisher; updated billing endpoints for admin and customer; improved API reference documentation; fixed endpoint paths in frontend services.
This commit is contained in:
IGNY8 VPS (Salman)
@@ -95,12 +95,35 @@ Development: http://localhost:8000/api/v1/
|
||||
```
|
||||
/api/v1/
|
||||
├── auth/ # Authentication and user management
|
||||
├── account/ # Account settings, team, and usage analytics
|
||||
├── integration/ # Site integrations and sync
|
||||
├── system/ # Settings, prompts, integrations
|
||||
├── admin/billing/ # Admin-only billing management
|
||||
├── billing/ # Credits, transactions, usage
|
||||
├── planner/ # Keywords, clusters, content ideas
|
||||
├── writer/ # Tasks, content, images
|
||||
├── system/ # Settings, prompts, integrations
|
||||
└── billing/ # Credits, transactions, usage
|
||||
├── automation/ # Automation configuration and runs
|
||||
├── linker/ # Internal linking operations
|
||||
├── optimizer/ # Content optimization operations
|
||||
└── publisher/ # Publishing records and deployments
|
||||
```
|
||||
|
||||
### Module → Tag Map (Swagger/ReDoc)
|
||||
- Authentication → `Authentication`
|
||||
- Account → `Account`
|
||||
- Integration → `Integration`
|
||||
- System → `System`
|
||||
- Admin Billing → `Admin Billing`
|
||||
- Billing → `Billing`
|
||||
- Planner → `Planner`
|
||||
- Writer → `Writer`
|
||||
- Automation → `Automation`
|
||||
- Linker → `Linker`
|
||||
- Optimizer → `Optimizer`
|
||||
- Publisher → `Publisher`
|
||||
|
||||
Tag display order (docs): Authentication, Account, Integration, System, Admin Billing, Billing, Planner, Writer, Automation, Linker, Optimizer, Publisher
|
||||
|
||||
### Technology Stack
|
||||
|
||||
- **Framework**: Django REST Framework (DRF)
|
||||
@@ -985,6 +1008,30 @@ class KeywordViewSet(SiteSectorModelViewSet):
|
||||
- `GET /api/v1/system/ping/` - Health check endpoint (AllowAny)
|
||||
- `GET /api/v1/system/request-metrics/{request_id}/` - Get request metrics for debugging
|
||||
|
||||
### Admin Billing & Credits (Admin-only, Unified)
|
||||
|
||||
**Base Path**: `/api/v1/admin/billing/` (all admin billing/credits live here)
|
||||
|
||||
- `GET /api/v1/admin/billing/stats/` - System billing stats (admin-only)
|
||||
- `GET /api/v1/admin/billing/invoices/` - Admin invoice listing (all accounts)
|
||||
- `GET /api/v1/admin/billing/payments/` - Admin payment listing (all accounts)
|
||||
- `GET /api/v1/admin/billing/pending_payments/` - Pending manual payments (admin review queue)
|
||||
- `POST /api/v1/admin/billing/{id}/approve_payment/` - Approve manual payment (admin-only)
|
||||
- `POST /api/v1/admin/billing/{id}/reject_payment/` - Reject manual payment (admin-only)
|
||||
- `GET /api/v1/admin/credit-costs/` - List credit cost configurations (admin-only)
|
||||
- `POST /api/v1/admin/credit-costs/` - Update credit cost configurations (admin-only)
|
||||
- `GET /api/v1/admin/users/` - List users/accounts with credit info (admin-only)
|
||||
- `POST /api/v1/admin/users/{user_id}/adjust-credits/` - Adjust user credits (admin-only)
|
||||
|
||||
> Non-standard/legacy endpoints to deprecate and remove (do not use):
|
||||
> - `/api/v1/billing/admin/stats/`
|
||||
> - `/api/v1/billing/admin/invoices/`
|
||||
> - `/api/v1/billing/admin/payments/`
|
||||
> - `/api/v1/billing/admin/pending_payments/`
|
||||
> - `/api/v1/billing/admin/{id}/approve_payment/`
|
||||
> - `/api/v1/billing/admin/{id}/reject_payment/`
|
||||
|
||||
|
||||
### Billing Module Endpoints
|
||||
|
||||
**Base Path**: `/api/v1/billing/`
|
||||
@@ -994,7 +1041,7 @@ class KeywordViewSet(SiteSectorModelViewSet):
|
||||
**Base Path**: `/api/v1/billing/credits/balance/`
|
||||
**Permission**: IsAuthenticatedAndActive + HasTenantAccess
|
||||
|
||||
- `GET /api/v1/billing/credits/balance/balance/` - Get credit balance
|
||||
- `GET /api/v1/billing/credits/balance/` - Get credit balance
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
@@ -1041,6 +1088,52 @@ class KeywordViewSet(SiteSectorModelViewSet):
|
||||
- `start_date` - Filter by start date
|
||||
- `end_date` - Filter by end date
|
||||
|
||||
#### Credit Packages
|
||||
|
||||
**Base Path**: `/api/v1/billing/credit-packages/`
|
||||
**Permission**: IsAuthenticated
|
||||
|
||||
- `GET /api/v1/billing/credit-packages/` - List available credit packages
|
||||
- `POST /api/v1/billing/credit-packages/{id}/purchase/` - Purchase a credit package
|
||||
|
||||
#### Invoices
|
||||
|
||||
**Base Path**: `/api/v1/billing/invoices/`
|
||||
**Permission**: IsAuthenticated
|
||||
|
||||
- `GET /api/v1/billing/invoices/` - List invoices
|
||||
- `GET /api/v1/billing/invoices/{id}/` - Get invoice detail
|
||||
- `GET /api/v1/billing/invoices/{id}/download_pdf/` - Download invoice PDF
|
||||
|
||||
#### Payment Methods
|
||||
|
||||
**Base Path**: `/api/v1/billing/payment-methods/`
|
||||
**Permission**: IsAuthenticated
|
||||
|
||||
- `GET /api/v1/billing/payment-methods/` - List payment methods
|
||||
- `POST /api/v1/billing/payment-methods/` - Create payment method
|
||||
- `GET /api/v1/billing/payment-methods/{id}/` - Get payment method
|
||||
- `PUT /api/v1/billing/payment-methods/{id}/` - Update payment method
|
||||
- `PATCH /api/v1/billing/payment-methods/{id}/` - Partial update payment method
|
||||
- `DELETE /api/v1/billing/payment-methods/{id}/` - Delete payment method
|
||||
- `POST /api/v1/billing/payment-methods/{id}/set_default/` - Set default payment method
|
||||
- `GET /api/v1/billing/payment-methods/available/` - List available payment methods (config-driven)
|
||||
|
||||
#### Payments
|
||||
|
||||
**Base Path**: `/api/v1/billing/payments/`
|
||||
**Permission**: IsAuthenticated
|
||||
|
||||
- `GET /api/v1/billing/payments/` - List payments
|
||||
- `POST /api/v1/billing/payments/manual/` - Submit manual payment for approval
|
||||
|
||||
#### Transactions (alias-free)
|
||||
|
||||
**Base Path**: `/api/v1/billing/transactions/`
|
||||
**Permission**: IsAuthenticated
|
||||
|
||||
- `GET /api/v1/billing/transactions/` - List transactions (with current balance included)
|
||||
|
||||
---
|
||||
|
||||
## Integration Examples
|
||||
@@ -1348,6 +1441,28 @@ All API changes are documented in `CHANGELOG.md` with:
|
||||
- Affected areas
|
||||
- Migration notes (if applicable)
|
||||
|
||||
### Endpoint Change & Documentation Checklist (Unified API)
|
||||
|
||||
1) Design
|
||||
- Map to an existing module/tag; if new, add to Module Namespaces and Tag Map.
|
||||
- Choose path under the correct base (`/api/v1/{module}/...`); avoid new sub-namespaces unless justified.
|
||||
|
||||
2) Implement
|
||||
- Use unified response helpers and proper permissions/rate limits.
|
||||
- Add `extend_schema` tags matching the module tag.
|
||||
|
||||
3) Schema & Docs
|
||||
- Ensure swagger tag exists in `SPECTACULAR_SETTINGS` with the agreed order.
|
||||
- Regenerate/reload the API (server restart) so `/api/schema/` reflects changes.
|
||||
- Verify in Swagger UI (`/api/docs/`) and ReDoc (`/api/redoc/`) that the operation is under the right tag.
|
||||
|
||||
4) Reference Updates
|
||||
- Update this reference file with the new endpoint(s) under the correct module section.
|
||||
- Update `CHANGELOG.md` (type, summary, impacted clients).
|
||||
|
||||
5) Deprecation (if applicable)
|
||||
- Mark legacy routes, add timeline, and keep compatibility shims only temporarily.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Reference in New Issue
Block a user