Consolidate API documentation into single unified reference
- Created docs/API-COMPLETE-REFERENCE.md as single source of truth - Removed redundant API documentation files: - docs/API-DOCUMENTATION.md - docs/DOCUMENTATION-SUMMARY.md - docs/README.md - unified-api/API-ENDPOINTS-ANALYSIS.md - unified-api/API-STANDARD-v1.0.md - Updated main README.md with API documentation section - Updated CHANGELOG.md with documentation consolidation details
This commit is contained in:
IGNY8 VPS (Salman)
13
CHANGELOG.md
13
CHANGELOG.md
@@ -26,6 +26,17 @@ Each entry follows this format:
|
|||||||
|
|
||||||
## [Unreleased]
|
## [Unreleased]
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- **API Documentation Consolidation**: Consolidated all API documentation into single comprehensive reference
|
||||||
|
- Created `docs/API-COMPLETE-REFERENCE.md` - Unified API documentation covering all endpoints, authentication, response formats, error handling, rate limiting, permissions, and integration examples
|
||||||
|
- Removed redundant documentation files:
|
||||||
|
- `docs/API-DOCUMENTATION.md` (consolidated into complete reference)
|
||||||
|
- `docs/DOCUMENTATION-SUMMARY.md` (consolidated into complete reference)
|
||||||
|
- `unified-api/API-ENDPOINTS-ANALYSIS.md` (consolidated into complete reference)
|
||||||
|
- `unified-api/API-STANDARD-v1.0.md` (consolidated into complete reference)
|
||||||
|
- New unified document includes: complete endpoint reference, authentication guide, response format standards, error handling, rate limiting, pagination, roles & permissions, tenant/site/sector scoping, integration examples (Python, JavaScript, cURL, PHP), testing & debugging, and change management
|
||||||
|
- **Impact**: Single source of truth for all API documentation, easier to maintain and navigate
|
||||||
|
|
||||||
### Added
|
### Added
|
||||||
- Unified API Standard v1.0 implementation
|
- Unified API Standard v1.0 implementation
|
||||||
- API Monitor page for endpoint health monitoring
|
- API Monitor page for endpoint health monitoring
|
||||||
@@ -353,7 +364,7 @@ Each entry follows this format:
|
|||||||
- Added custom authentication extensions for JWT Bearer tokens
|
- Added custom authentication extensions for JWT Bearer tokens
|
||||||
|
|
||||||
- **Comprehensive Documentation Files**
|
- **Comprehensive Documentation Files**
|
||||||
- `docs/API-DOCUMENTATION.md` - Complete API reference with examples
|
- `docs/API-COMPLETE-REFERENCE.md` - Complete unified API reference (consolidated from multiple files)
|
||||||
- Quick start guide
|
- Quick start guide
|
||||||
- Endpoint reference
|
- Endpoint reference
|
||||||
- Code examples (Python, JavaScript, cURL)
|
- Code examples (Python, JavaScript, cURL)
|
||||||
|
|||||||
66
README.md
66
README.md
@@ -44,7 +44,8 @@ igny8/
|
|||||||
│ ├── 03-FRONTEND-ARCHITECTURE.md
|
│ ├── 03-FRONTEND-ARCHITECTURE.md
|
||||||
│ ├── 04-BACKEND-IMPLEMENTATION.md
|
│ ├── 04-BACKEND-IMPLEMENTATION.md
|
||||||
│ ├── 05-AI-FRAMEWORK-IMPLEMENTATION.md
|
│ ├── 05-AI-FRAMEWORK-IMPLEMENTATION.md
|
||||||
│ └── 06-FUNCTIONAL-BUSINESS-LOGIC.md
|
│ ├── 06-FUNCTIONAL-BUSINESS-LOGIC.md
|
||||||
|
│ └── API-COMPLETE-REFERENCE.md # Complete unified API documentation
|
||||||
├── CHANGELOG.md # Version history and changes (only updated after user confirmation)
|
├── CHANGELOG.md # Version history and changes (only updated after user confirmation)
|
||||||
└── docker-compose.app.yml
|
└── docker-compose.app.yml
|
||||||
```
|
```
|
||||||
@@ -132,16 +133,62 @@ For complete installation guide, see [docs/01-TECH-STACK-AND-INFRASTRUCTURE.md](
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔗 API Endpoints
|
## 🔗 API Documentation
|
||||||
|
|
||||||
- **Planner**: `/api/v1/planner/keywords/`, `/api/v1/planner/clusters/`, `/api/v1/planner/ideas/`
|
### Interactive Documentation
|
||||||
- **Writer**: `/api/v1/writer/tasks/`, `/api/v1/writer/images/`
|
|
||||||
- **System**: `/api/v1/system/settings/`
|
|
||||||
- **Billing**: `/api/v1/billing/`
|
|
||||||
- **Auth**: `/api/v1/auth/`
|
|
||||||
- **Admin**: `/admin/`
|
|
||||||
|
|
||||||
See [docs/04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md) for complete API reference.
|
- **Swagger UI**: `https://api.igny8.com/api/docs/`
|
||||||
|
- **ReDoc**: `https://api.igny8.com/api/redoc/`
|
||||||
|
- **OpenAPI Schema**: `https://api.igny8.com/api/schema/`
|
||||||
|
|
||||||
|
### API Complete Reference
|
||||||
|
|
||||||
|
**[API Complete Reference](docs/API-COMPLETE-REFERENCE.md)** - Comprehensive unified API documentation (single source of truth)
|
||||||
|
- Complete endpoint reference (100+ endpoints across all modules)
|
||||||
|
- Authentication & authorization guide
|
||||||
|
- Response format standards (unified format: `{success, data, message, errors, request_id}`)
|
||||||
|
- Error handling
|
||||||
|
- Rate limiting (scoped by operation type)
|
||||||
|
- Pagination
|
||||||
|
- Roles & permissions
|
||||||
|
- Tenant/site/sector scoping
|
||||||
|
- Integration examples (Python, JavaScript, cURL, PHP)
|
||||||
|
- Testing & debugging
|
||||||
|
- Change management
|
||||||
|
|
||||||
|
### API Standard Features
|
||||||
|
|
||||||
|
- ✅ **Unified Response Format** - Consistent JSON structure for all endpoints
|
||||||
|
- ✅ **Layered Authorization** - Authentication → Tenant → Role → Site/Sector
|
||||||
|
- ✅ **Centralized Error Handling** - All errors in unified format with request_id
|
||||||
|
- ✅ **Scoped Rate Limiting** - Different limits per operation type (10-100/min)
|
||||||
|
- ✅ **Tenant Isolation** - Account/site/sector scoping
|
||||||
|
- ✅ **Request Tracking** - Unique request ID for debugging
|
||||||
|
- ✅ **100% Implemented** - All endpoints use unified format
|
||||||
|
|
||||||
|
### Quick API Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Login
|
||||||
|
curl -X POST https://api.igny8.com/api/v1/auth/login/ \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"email":"user@example.com","password":"password"}'
|
||||||
|
|
||||||
|
# Get keywords (with token)
|
||||||
|
curl -X GET https://api.igny8.com/api/v1/planner/keywords/ \
|
||||||
|
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||||
|
-H "Content-Type: application/json"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Additional API Guides
|
||||||
|
|
||||||
|
- **[Authentication Guide](docs/AUTHENTICATION-GUIDE.md)** - Detailed JWT authentication guide
|
||||||
|
- **[Error Codes Reference](docs/ERROR-CODES.md)** - Complete error code reference
|
||||||
|
- **[Rate Limiting Guide](docs/RATE-LIMITING.md)** - Rate limiting and throttling details
|
||||||
|
- **[Migration Guide](docs/MIGRATION-GUIDE.md)** - Migrating to API v1.0
|
||||||
|
- **[WordPress Plugin Integration](docs/WORDPRESS-PLUGIN-INTEGRATION.md)** - WordPress integration guide
|
||||||
|
|
||||||
|
For backend implementation details, see [docs/04-BACKEND-IMPLEMENTATION.md](docs/04-BACKEND-IMPLEMENTATION.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -234,6 +281,7 @@ All documentation is consolidated in the `/docs/` folder.
|
|||||||
### Finding Information
|
### Finding Information
|
||||||
|
|
||||||
**By Topic:**
|
**By Topic:**
|
||||||
|
- **API Documentation**: [API-COMPLETE-REFERENCE.md](docs/API-COMPLETE-REFERENCE.md) - Complete unified API reference (single source of truth)
|
||||||
- **Infrastructure & Deployment**: [01-TECH-STACK-AND-INFRASTRUCTURE.md](docs/01-TECH-STACK-AND-INFRASTRUCTURE.md)
|
- **Infrastructure & Deployment**: [01-TECH-STACK-AND-INFRASTRUCTURE.md](docs/01-TECH-STACK-AND-INFRASTRUCTURE.md)
|
||||||
- **Application Architecture**: [02-APPLICATION-ARCHITECTURE.md](docs/02-APPLICATION-ARCHITECTURE.md)
|
- **Application Architecture**: [02-APPLICATION-ARCHITECTURE.md](docs/02-APPLICATION-ARCHITECTURE.md)
|
||||||
- **Frontend Development**: [03-FRONTEND-ARCHITECTURE.md](docs/03-FRONTEND-ARCHITECTURE.md)
|
- **Frontend Development**: [03-FRONTEND-ARCHITECTURE.md](docs/03-FRONTEND-ARCHITECTURE.md)
|
||||||
|
|||||||
1389
docs/API-COMPLETE-REFERENCE.md
Normal file
1389
docs/API-COMPLETE-REFERENCE.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -1,545 +0,0 @@
|
|||||||
# IGNY8 API Documentation v1.0
|
|
||||||
|
|
||||||
**Base URL**: `https://api.igny8.com/api/v1/`
|
|
||||||
**Version**: 1.0.0
|
|
||||||
**Last Updated**: 2025-11-16
|
|
||||||
|
|
||||||
## Quick Links
|
|
||||||
|
|
||||||
- [Interactive API Documentation (Swagger UI)](#swagger-ui)
|
|
||||||
- [Authentication Guide](#authentication)
|
|
||||||
- [Response Format](#response-format)
|
|
||||||
- [Error Handling](#error-handling)
|
|
||||||
- [Rate Limiting](#rate-limiting)
|
|
||||||
- [Pagination](#pagination)
|
|
||||||
- [Endpoint Reference](#endpoint-reference)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Swagger UI
|
|
||||||
|
|
||||||
Interactive API documentation is available at:
|
|
||||||
- **Swagger UI**: `https://api.igny8.com/api/docs/`
|
|
||||||
- **ReDoc**: `https://api.igny8.com/api/redoc/`
|
|
||||||
- **OpenAPI Schema**: `https://api.igny8.com/api/schema/`
|
|
||||||
|
|
||||||
The Swagger UI provides:
|
|
||||||
- Interactive endpoint testing
|
|
||||||
- Request/response examples
|
|
||||||
- Authentication testing
|
|
||||||
- Schema definitions
|
|
||||||
- Code samples in multiple languages
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
### JWT Bearer Token
|
|
||||||
|
|
||||||
All endpoints require JWT Bearer token authentication except:
|
|
||||||
- `POST /api/v1/auth/login/` - User login
|
|
||||||
- `POST /api/v1/auth/register/` - User registration
|
|
||||||
|
|
||||||
### Getting an Access Token
|
|
||||||
|
|
||||||
**Login Endpoint:**
|
|
||||||
```http
|
|
||||||
POST /api/v1/auth/login/
|
|
||||||
Content-Type: application/json
|
|
||||||
|
|
||||||
{
|
|
||||||
"email": "user@example.com",
|
|
||||||
"password": "your_password"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"user": {
|
|
||||||
"id": 1,
|
|
||||||
"email": "user@example.com",
|
|
||||||
"username": "user",
|
|
||||||
"role": "owner"
|
|
||||||
},
|
|
||||||
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
||||||
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|
||||||
},
|
|
||||||
"request_id": "uuid"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Using the Token
|
|
||||||
|
|
||||||
Include the token in the `Authorization` header:
|
|
||||||
|
|
||||||
```http
|
|
||||||
GET /api/v1/planner/keywords/
|
|
||||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
### Token Expiration
|
|
||||||
|
|
||||||
- **Access Token**: 15 minutes
|
|
||||||
- **Refresh Token**: 7 days
|
|
||||||
|
|
||||||
Use the refresh token to get a new access token:
|
|
||||||
```http
|
|
||||||
POST /api/v1/auth/refresh/
|
|
||||||
Content-Type: application/json
|
|
||||||
|
|
||||||
{
|
|
||||||
"refresh": "your_refresh_token"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Response Format
|
|
||||||
|
|
||||||
### Success Response
|
|
||||||
|
|
||||||
All successful responses follow this unified format:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"id": 1,
|
|
||||||
"name": "Example",
|
|
||||||
...
|
|
||||||
},
|
|
||||||
"message": "Optional success message",
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Paginated Response
|
|
||||||
|
|
||||||
List endpoints return paginated data:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"count": 100,
|
|
||||||
"next": "https://api.igny8.com/api/v1/planner/keywords/?page=2",
|
|
||||||
"previous": null,
|
|
||||||
"results": [
|
|
||||||
{"id": 1, "name": "Keyword 1"},
|
|
||||||
{"id": 2, "name": "Keyword 2"},
|
|
||||||
...
|
|
||||||
],
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Error Response
|
|
||||||
|
|
||||||
All error responses follow this unified format:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": "Validation failed",
|
|
||||||
"errors": {
|
|
||||||
"email": ["This field is required"],
|
|
||||||
"password": ["Password too short"]
|
|
||||||
},
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Error Handling
|
|
||||||
|
|
||||||
### HTTP Status Codes
|
|
||||||
|
|
||||||
| Code | Meaning | Description |
|
|
||||||
|------|---------|-------------|
|
|
||||||
| 200 | OK | Request successful |
|
|
||||||
| 201 | Created | Resource created successfully |
|
|
||||||
| 204 | No Content | Resource deleted successfully |
|
|
||||||
| 400 | Bad Request | Validation error or invalid request |
|
|
||||||
| 401 | Unauthorized | Authentication required |
|
|
||||||
| 403 | Forbidden | Permission denied |
|
|
||||||
| 404 | Not Found | Resource not found |
|
|
||||||
| 409 | Conflict | Resource conflict (e.g., duplicate) |
|
|
||||||
| 422 | Unprocessable Entity | Validation failed |
|
|
||||||
| 429 | Too Many Requests | Rate limit exceeded |
|
|
||||||
| 500 | Internal Server Error | Server error |
|
|
||||||
|
|
||||||
### Error Response Structure
|
|
||||||
|
|
||||||
All errors include:
|
|
||||||
- `success`: Always `false`
|
|
||||||
- `error`: Top-level error message
|
|
||||||
- `errors`: Field-specific errors (for validation errors)
|
|
||||||
- `request_id`: Unique request ID for debugging
|
|
||||||
|
|
||||||
### Example Error Responses
|
|
||||||
|
|
||||||
**Validation Error (400):**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": "Validation failed",
|
|
||||||
"errors": {
|
|
||||||
"email": ["Invalid email format"],
|
|
||||||
"password": ["Password must be at least 8 characters"]
|
|
||||||
},
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Authentication Error (401):**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": "Authentication required",
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Permission Error (403):**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": "Permission denied",
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Not Found (404):**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": "Resource not found",
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Rate Limit (429):**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": "Rate limit exceeded",
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Rate Limiting
|
|
||||||
|
|
||||||
Rate limits are scoped by operation type. Check response headers for limit information:
|
|
||||||
|
|
||||||
- `X-Throttle-Limit`: Maximum requests allowed
|
|
||||||
- `X-Throttle-Remaining`: Remaining requests in current window
|
|
||||||
- `X-Throttle-Reset`: Time when limit resets (Unix timestamp)
|
|
||||||
|
|
||||||
### Rate Limit Scopes
|
|
||||||
|
|
||||||
| Scope | Limit | Description |
|
|
||||||
|-------|-------|-------------|
|
|
||||||
| `ai_function` | 10/min | AI content generation, clustering |
|
|
||||||
| `image_gen` | 15/min | Image generation |
|
|
||||||
| `content_write` | 30/min | Content creation, updates |
|
|
||||||
| `content_read` | 100/min | Content listing, retrieval |
|
|
||||||
| `auth` | 20/min | Login, register, password reset |
|
|
||||||
| `auth_strict` | 5/min | Sensitive auth operations |
|
|
||||||
| `planner` | 60/min | Keyword, cluster, idea operations |
|
|
||||||
| `planner_ai` | 10/min | AI-powered planner operations |
|
|
||||||
| `writer` | 60/min | Task, content management |
|
|
||||||
| `writer_ai` | 10/min | AI-powered writer operations |
|
|
||||||
| `system` | 100/min | Settings, prompts, profiles |
|
|
||||||
| `system_admin` | 30/min | Admin-only system operations |
|
|
||||||
| `billing` | 30/min | Credit queries, usage logs |
|
|
||||||
| `billing_admin` | 10/min | Credit management (admin) |
|
|
||||||
| `default` | 100/min | Default for endpoints without scope |
|
|
||||||
|
|
||||||
### Handling Rate Limits
|
|
||||||
|
|
||||||
When rate limited (429), the response includes:
|
|
||||||
- Error message: "Rate limit exceeded"
|
|
||||||
- Headers with reset time
|
|
||||||
- Wait until `X-Throttle-Reset` before retrying
|
|
||||||
|
|
||||||
**Example:**
|
|
||||||
```http
|
|
||||||
HTTP/1.1 429 Too Many Requests
|
|
||||||
X-Throttle-Limit: 60
|
|
||||||
X-Throttle-Remaining: 0
|
|
||||||
X-Throttle-Reset: 1700123456
|
|
||||||
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": "Rate limit exceeded",
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Pagination
|
|
||||||
|
|
||||||
List endpoints support pagination with query parameters:
|
|
||||||
|
|
||||||
- `page`: Page number (default: 1)
|
|
||||||
- `page_size`: Items per page (default: 10, max: 100)
|
|
||||||
|
|
||||||
### Example Request
|
|
||||||
|
|
||||||
```http
|
|
||||||
GET /api/v1/planner/keywords/?page=2&page_size=20
|
|
||||||
```
|
|
||||||
|
|
||||||
### Paginated Response
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"count": 100,
|
|
||||||
"next": "https://api.igny8.com/api/v1/planner/keywords/?page=3&page_size=20",
|
|
||||||
"previous": "https://api.igny8.com/api/v1/planner/keywords/?page=1&page_size=20",
|
|
||||||
"results": [
|
|
||||||
{"id": 21, "name": "Keyword 21"},
|
|
||||||
{"id": 22, "name": "Keyword 22"},
|
|
||||||
...
|
|
||||||
],
|
|
||||||
"request_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Pagination Fields
|
|
||||||
|
|
||||||
- `count`: Total number of items
|
|
||||||
- `next`: URL to next page (null if last page)
|
|
||||||
- `previous`: URL to previous page (null if first page)
|
|
||||||
- `results`: Array of items for current page
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Endpoint Reference
|
|
||||||
|
|
||||||
### Authentication Endpoints
|
|
||||||
|
|
||||||
#### Login
|
|
||||||
```http
|
|
||||||
POST /api/v1/auth/login/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Register
|
|
||||||
```http
|
|
||||||
POST /api/v1/auth/register/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Refresh Token
|
|
||||||
```http
|
|
||||||
POST /api/v1/auth/refresh/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Planner Endpoints
|
|
||||||
|
|
||||||
#### List Keywords
|
|
||||||
```http
|
|
||||||
GET /api/v1/planner/keywords/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Create Keyword
|
|
||||||
```http
|
|
||||||
POST /api/v1/planner/keywords/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Get Keyword
|
|
||||||
```http
|
|
||||||
GET /api/v1/planner/keywords/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Update Keyword
|
|
||||||
```http
|
|
||||||
PUT /api/v1/planner/keywords/{id}/
|
|
||||||
PATCH /api/v1/planner/keywords/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Delete Keyword
|
|
||||||
```http
|
|
||||||
DELETE /api/v1/planner/keywords/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Auto Cluster Keywords
|
|
||||||
```http
|
|
||||||
POST /api/v1/planner/keywords/auto_cluster/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Writer Endpoints
|
|
||||||
|
|
||||||
#### List Tasks
|
|
||||||
```http
|
|
||||||
GET /api/v1/writer/tasks/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Create Task
|
|
||||||
```http
|
|
||||||
POST /api/v1/writer/tasks/
|
|
||||||
```
|
|
||||||
|
|
||||||
### System Endpoints
|
|
||||||
|
|
||||||
#### System Status
|
|
||||||
```http
|
|
||||||
GET /api/v1/system/status/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### List Prompts
|
|
||||||
```http
|
|
||||||
GET /api/v1/system/prompts/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Billing Endpoints
|
|
||||||
|
|
||||||
#### Credit Balance
|
|
||||||
```http
|
|
||||||
GET /api/v1/billing/credits/balance/balance/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Usage Summary
|
|
||||||
```http
|
|
||||||
GET /api/v1/billing/credits/usage/summary/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Code Examples
|
|
||||||
|
|
||||||
### Python
|
|
||||||
|
|
||||||
```python
|
|
||||||
import requests
|
|
||||||
|
|
||||||
BASE_URL = "https://api.igny8.com/api/v1"
|
|
||||||
|
|
||||||
# Login
|
|
||||||
response = requests.post(
|
|
||||||
f"{BASE_URL}/auth/login/",
|
|
||||||
json={"email": "user@example.com", "password": "password"}
|
|
||||||
)
|
|
||||||
data = response.json()
|
|
||||||
|
|
||||||
if data['success']:
|
|
||||||
token = data['data']['access']
|
|
||||||
|
|
||||||
# Use token for authenticated requests
|
|
||||||
headers = {
|
|
||||||
'Authorization': f'Bearer {token}',
|
|
||||||
'Content-Type': 'application/json'
|
|
||||||
}
|
|
||||||
|
|
||||||
# Get keywords
|
|
||||||
response = requests.get(
|
|
||||||
f"{BASE_URL}/planner/keywords/",
|
|
||||||
headers=headers
|
|
||||||
)
|
|
||||||
keywords_data = response.json()
|
|
||||||
|
|
||||||
if keywords_data['success']:
|
|
||||||
keywords = keywords_data['results']
|
|
||||||
print(f"Found {keywords_data['count']} keywords")
|
|
||||||
else:
|
|
||||||
print(f"Error: {keywords_data['error']}")
|
|
||||||
else:
|
|
||||||
print(f"Login failed: {data['error']}")
|
|
||||||
```
|
|
||||||
|
|
||||||
### JavaScript
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
const BASE_URL = 'https://api.igny8.com/api/v1';
|
|
||||||
|
|
||||||
// Login
|
|
||||||
const loginResponse = await fetch(`${BASE_URL}/auth/login/`, {
|
|
||||||
method: 'POST',
|
|
||||||
headers: {
|
|
||||||
'Content-Type': 'application/json'
|
|
||||||
},
|
|
||||||
body: JSON.stringify({
|
|
||||||
email: 'user@example.com',
|
|
||||||
password: 'password'
|
|
||||||
})
|
|
||||||
});
|
|
||||||
|
|
||||||
const loginData = await loginResponse.json();
|
|
||||||
|
|
||||||
if (loginData.success) {
|
|
||||||
const token = loginData.data.access;
|
|
||||||
|
|
||||||
// Use token for authenticated requests
|
|
||||||
const headers = {
|
|
||||||
'Authorization': `Bearer ${token}`,
|
|
||||||
'Content-Type': 'application/json'
|
|
||||||
};
|
|
||||||
|
|
||||||
// Get keywords
|
|
||||||
const keywordsResponse = await fetch(
|
|
||||||
`${BASE_URL}/planner/keywords/`,
|
|
||||||
{ headers }
|
|
||||||
);
|
|
||||||
|
|
||||||
const keywordsData = await keywordsResponse.json();
|
|
||||||
|
|
||||||
if (keywordsData.success) {
|
|
||||||
const keywords = keywordsData.results;
|
|
||||||
console.log(`Found ${keywordsData.count} keywords`);
|
|
||||||
} else {
|
|
||||||
console.error('Error:', keywordsData.error);
|
|
||||||
}
|
|
||||||
} else {
|
|
||||||
console.error('Login failed:', loginData.error);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### cURL
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Login
|
|
||||||
curl -X POST https://api.igny8.com/api/v1/auth/login/ \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{"email":"user@example.com","password":"password"}'
|
|
||||||
|
|
||||||
# Get keywords (with token)
|
|
||||||
curl -X GET https://api.igny8.com/api/v1/planner/keywords/ \
|
|
||||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
|
||||||
-H "Content-Type: application/json"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Request ID
|
|
||||||
|
|
||||||
Every API request includes a unique `request_id` in the response. Use this ID for:
|
|
||||||
- Debugging issues
|
|
||||||
- Log correlation
|
|
||||||
- Support requests
|
|
||||||
|
|
||||||
The `request_id` is included in:
|
|
||||||
- All success responses
|
|
||||||
- All error responses
|
|
||||||
- Response headers (`X-Request-ID`)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
For API support:
|
|
||||||
- Check the [Interactive Documentation](https://api.igny8.com/api/docs/)
|
|
||||||
- Review [Error Codes Reference](ERROR-CODES.md)
|
|
||||||
- Contact support with your `request_id`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Last Updated**: 2025-11-16
|
|
||||||
**API Version**: 1.0.0
|
|
||||||
|
|
||||||
@@ -1,210 +0,0 @@
|
|||||||
# Documentation Implementation Summary
|
|
||||||
|
|
||||||
**Section 2: Documentation - COMPLETE** ✅
|
|
||||||
|
|
||||||
**Date Completed**: 2025-11-16
|
|
||||||
**Last Updated**: 2025-01-XX
|
|
||||||
**Status**: All Documentation Complete and Ready
|
|
||||||
|
|
||||||
**API Standard v1.0**: ✅ **100% COMPLIANT** - All remaining items completed
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Implementation Overview
|
|
||||||
|
|
||||||
Complete documentation system for IGNY8 API v1.0 including:
|
|
||||||
- OpenAPI 3.0 schema generation
|
|
||||||
- Interactive Swagger UI
|
|
||||||
- Comprehensive documentation files
|
|
||||||
- Code examples and integration guides
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## OpenAPI/Swagger Integration ✅
|
|
||||||
|
|
||||||
### Configuration
|
|
||||||
- ✅ Installed `drf-spectacular>=0.27.0`
|
|
||||||
- ✅ Added to `INSTALLED_APPS`
|
|
||||||
- ✅ Configured `SPECTACULAR_SETTINGS` with comprehensive description
|
|
||||||
- ✅ Added URL endpoints for schema and documentation
|
|
||||||
|
|
||||||
### Endpoints Created
|
|
||||||
- ✅ `/api/schema/` - OpenAPI 3.0 schema (JSON/YAML)
|
|
||||||
- ✅ `/api/docs/` - Swagger UI (interactive documentation)
|
|
||||||
- ✅ `/api/redoc/` - ReDoc (alternative documentation UI)
|
|
||||||
|
|
||||||
### Features
|
|
||||||
- ✅ Comprehensive API description with features overview
|
|
||||||
- ✅ Authentication documentation (JWT Bearer tokens)
|
|
||||||
- ✅ Response format examples
|
|
||||||
- ✅ Rate limiting documentation
|
|
||||||
- ✅ Pagination documentation
|
|
||||||
- ✅ Endpoint tags (Authentication, Planner, Writer, System, Billing)
|
|
||||||
- ✅ Code samples in Python and JavaScript
|
|
||||||
- ✅ Custom authentication extensions
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Documentation Files Created ✅
|
|
||||||
|
|
||||||
### 1. API-DOCUMENTATION.md
|
|
||||||
**Purpose**: Complete API reference
|
|
||||||
**Contents**:
|
|
||||||
- Quick start guide
|
|
||||||
- Authentication guide
|
|
||||||
- Response format details
|
|
||||||
- Error handling
|
|
||||||
- Rate limiting
|
|
||||||
- Pagination
|
|
||||||
- Endpoint reference
|
|
||||||
- Code examples (Python, JavaScript, cURL)
|
|
||||||
|
|
||||||
### 2. AUTHENTICATION-GUIDE.md
|
|
||||||
**Purpose**: Authentication and authorization
|
|
||||||
**Contents**:
|
|
||||||
- JWT Bearer token authentication
|
|
||||||
- Token management and refresh
|
|
||||||
- Code examples (Python, JavaScript)
|
|
||||||
- Security best practices
|
|
||||||
- Token expiration handling
|
|
||||||
- Troubleshooting
|
|
||||||
|
|
||||||
### 3. ERROR-CODES.md
|
|
||||||
**Purpose**: Complete error code reference
|
|
||||||
**Contents**:
|
|
||||||
- HTTP status codes (200, 201, 400, 401, 403, 404, 409, 422, 429, 500)
|
|
||||||
- Field-specific error messages
|
|
||||||
- Error handling best practices
|
|
||||||
- Common error scenarios
|
|
||||||
- Debugging tips
|
|
||||||
|
|
||||||
### 4. RATE-LIMITING.md
|
|
||||||
**Purpose**: Rate limiting and throttling
|
|
||||||
**Contents**:
|
|
||||||
- Rate limit scopes and limits
|
|
||||||
- Handling rate limits (429 responses)
|
|
||||||
- Best practices
|
|
||||||
- Code examples with backoff strategies
|
|
||||||
- Request queuing and caching
|
|
||||||
|
|
||||||
### 5. MIGRATION-GUIDE.md
|
|
||||||
**Purpose**: Migration guide for API consumers
|
|
||||||
**Contents**:
|
|
||||||
- What changed in v1.0
|
|
||||||
- Step-by-step migration instructions
|
|
||||||
- Code examples (before/after)
|
|
||||||
- Breaking and non-breaking changes
|
|
||||||
- Migration checklist
|
|
||||||
|
|
||||||
### 6. WORDPRESS-PLUGIN-INTEGRATION.md
|
|
||||||
**Purpose**: WordPress plugin integration
|
|
||||||
**Contents**:
|
|
||||||
- Complete PHP API client class
|
|
||||||
- Authentication implementation
|
|
||||||
- Error handling
|
|
||||||
- WordPress admin integration
|
|
||||||
- Best practices
|
|
||||||
- Testing examples
|
|
||||||
|
|
||||||
### 7. README.md
|
|
||||||
**Purpose**: Documentation index
|
|
||||||
**Contents**:
|
|
||||||
- Documentation index
|
|
||||||
- Quick start guide
|
|
||||||
- Links to all documentation files
|
|
||||||
- Support information
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Schema Extensions ✅
|
|
||||||
|
|
||||||
### Custom Authentication Extensions
|
|
||||||
- ✅ `JWTAuthenticationExtension` - JWT Bearer token authentication
|
|
||||||
- ✅ `CSRFExemptSessionAuthenticationExtension` - Session authentication
|
|
||||||
- ✅ Proper OpenAPI security scheme definitions
|
|
||||||
|
|
||||||
**File**: `backend/igny8_core/api/schema_extensions.py`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
### Schema Generation
|
|
||||||
```bash
|
|
||||||
python manage.py spectacular --color
|
|
||||||
```
|
|
||||||
**Status**: ✅ Schema generates successfully
|
|
||||||
|
|
||||||
### Documentation Endpoints
|
|
||||||
- ✅ `/api/schema/` - OpenAPI schema
|
|
||||||
- ✅ `/api/docs/` - Swagger UI
|
|
||||||
- ✅ `/api/redoc/` - ReDoc
|
|
||||||
|
|
||||||
### Documentation Files
|
|
||||||
- ✅ 7 comprehensive documentation files created
|
|
||||||
- ✅ All files include code examples
|
|
||||||
- ✅ All files include best practices
|
|
||||||
- ✅ All files properly formatted
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Documentation Statistics
|
|
||||||
|
|
||||||
- **Total Documentation Files**: 7
|
|
||||||
- **Total Pages**: ~100+ pages of documentation
|
|
||||||
- **Code Examples**: Python, JavaScript, PHP, cURL
|
|
||||||
- **Coverage**: 100% of API features documented
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## What's Documented
|
|
||||||
|
|
||||||
### ✅ API Features
|
|
||||||
- Unified response format
|
|
||||||
- Authentication and authorization
|
|
||||||
- Error handling
|
|
||||||
- Rate limiting
|
|
||||||
- Pagination
|
|
||||||
- Request ID tracking
|
|
||||||
|
|
||||||
### ✅ Integration Guides
|
|
||||||
- Python integration
|
|
||||||
- JavaScript integration
|
|
||||||
- WordPress plugin integration
|
|
||||||
- Migration from legacy format
|
|
||||||
|
|
||||||
### ✅ Reference Materials
|
|
||||||
- Error codes
|
|
||||||
- Rate limit scopes
|
|
||||||
- Endpoint reference
|
|
||||||
- Code examples
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Access Points
|
|
||||||
|
|
||||||
### Interactive Documentation
|
|
||||||
- **Swagger UI**: `https://api.igny8.com/api/docs/`
|
|
||||||
- **ReDoc**: `https://api.igny8.com/api/redoc/`
|
|
||||||
- **OpenAPI Schema**: `https://api.igny8.com/api/schema/`
|
|
||||||
|
|
||||||
### Documentation Files
|
|
||||||
- All files in `docs/` directory
|
|
||||||
- Index: `docs/README.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Next Steps
|
|
||||||
|
|
||||||
1. ✅ Documentation complete
|
|
||||||
2. ✅ Swagger UI accessible
|
|
||||||
3. ✅ All guides created
|
|
||||||
4. ✅ Changelog updated
|
|
||||||
|
|
||||||
**Section 2: Documentation is COMPLETE** ✅
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Last Updated**: 2025-11-16
|
|
||||||
**API Version**: 1.0.0
|
|
||||||
|
|
||||||
113
docs/README.md
113
docs/README.md
@@ -1,113 +0,0 @@
|
|||||||
# IGNY8 API Documentation
|
|
||||||
|
|
||||||
**Version**: 1.0.0
|
|
||||||
**Last Updated**: 2025-11-16
|
|
||||||
|
|
||||||
Complete documentation for the IGNY8 Unified API Standard v1.0.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Documentation Index
|
|
||||||
|
|
||||||
### Getting Started
|
|
||||||
|
|
||||||
1. **[API Documentation](API-DOCUMENTATION.md)** - Complete API reference with examples
|
|
||||||
- Quick start guide
|
|
||||||
- Endpoint reference
|
|
||||||
- Code examples (Python, JavaScript, cURL)
|
|
||||||
- Response format details
|
|
||||||
|
|
||||||
2. **[Authentication Guide](AUTHENTICATION-GUIDE.md)** - Authentication and authorization
|
|
||||||
- JWT Bearer token authentication
|
|
||||||
- Token management
|
|
||||||
- Code examples
|
|
||||||
- Security best practices
|
|
||||||
|
|
||||||
3. **[Error Codes Reference](ERROR-CODES.md)** - Complete error code reference
|
|
||||||
- HTTP status codes
|
|
||||||
- Field-specific errors
|
|
||||||
- Error handling best practices
|
|
||||||
- Common error scenarios
|
|
||||||
|
|
||||||
4. **[Rate Limiting Guide](RATE-LIMITING.md)** - Rate limiting and throttling
|
|
||||||
- Rate limit scopes
|
|
||||||
- Handling rate limits
|
|
||||||
- Best practices
|
|
||||||
- Code examples
|
|
||||||
|
|
||||||
### Integration Guides
|
|
||||||
|
|
||||||
5. **[Migration Guide](MIGRATION-GUIDE.md)** - Migrating to API v1.0
|
|
||||||
- What changed
|
|
||||||
- Step-by-step migration
|
|
||||||
- Code examples
|
|
||||||
- Breaking changes
|
|
||||||
|
|
||||||
6. **[WordPress Plugin Integration](WORDPRESS-PLUGIN-INTEGRATION.md)** - WordPress integration
|
|
||||||
- PHP API client
|
|
||||||
- Authentication
|
|
||||||
- Error handling
|
|
||||||
- Best practices
|
|
||||||
|
|
||||||
### Interactive Documentation
|
|
||||||
|
|
||||||
- **Swagger UI**: `https://api.igny8.com/api/docs/`
|
|
||||||
- **ReDoc**: `https://api.igny8.com/api/redoc/`
|
|
||||||
- **OpenAPI Schema**: `https://api.igny8.com/api/schema/`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Start
|
|
||||||
|
|
||||||
### 1. Get Access Token
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST https://api.igny8.com/api/v1/auth/login/ \
|
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{"email":"user@example.com","password":"password"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Use Token
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X GET https://api.igny8.com/api/v1/planner/keywords/ \
|
|
||||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
|
||||||
-H "Content-Type: application/json"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Handle Response
|
|
||||||
|
|
||||||
All responses follow unified format:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {...},
|
|
||||||
"request_id": "uuid"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## API Standard Features
|
|
||||||
|
|
||||||
- ✅ **Unified Response Format** - Consistent JSON structure
|
|
||||||
- ✅ **Layered Authorization** - Authentication → Tenant → Role → Site/Sector
|
|
||||||
- ✅ **Centralized Error Handling** - All errors in unified format
|
|
||||||
- ✅ **Scoped Rate Limiting** - Different limits per operation type
|
|
||||||
- ✅ **Tenant Isolation** - Account/site/sector scoping
|
|
||||||
- ✅ **Request Tracking** - Unique request ID for debugging
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
- **Interactive Docs**: [Swagger UI](https://api.igny8.com/api/docs/)
|
|
||||||
- **Error Reference**: [Error Codes](ERROR-CODES.md)
|
|
||||||
- **Contact**: Include `request_id` from responses when contacting support
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Last Updated**: 2025-11-16
|
|
||||||
**API Version**: 1.0.0
|
|
||||||
|
|
||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user