initial version

2026-01-25 08:57:55 +01:00
commit a538af46ce
33 changed files with 6662 additions and 0 deletions
@@ -0,0 +1,336 @@
+# API Documentation
+
+The SEO Optimizer provides a REST API for manual optimization triggers and managing drafts.
+
+## Base URL
+
+```
+http://localhost:8080/api/v1
+```
+
+## Endpoints
+
+### 1. Health Check
+
+Check if the API server is running.
+
+```bash
+GET /health
+```
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "version": "1.0.0"
+}
+```
+
+---
+
+### 2. Optimize Post
+
+Manually trigger optimization for a specific post.
+
+```bash
+POST /optimize
+Content-Type: application/json
+
+{
+  "post_id": 123,
+  "language": "es"
+}
+```
+
+**Parameters:**
+- `post_id` (int, required): WordPress post ID to optimize
+- `language` (string, optional): Language code (defaults to "en")
+
+**Response:**
+```json
+{
+  "job_id": "uuid-string",
+  "status": "accepted"
+}
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080/api/v1/optimize \
+  -H "Content-Type: application/json" \
+  -d '{"post_id": 123, "language": "es"}'
+```
+
+---
+
+### 3. Check Job Status
+
+Check the status of an optimization job.
+
+```bash
+GET /status/{job_id}
+```
+
+**Response:**
+```json
+{
+  "id": "uuid-string",
+  "post_id": 123,
+  "language": "es",
+  "status": "completed",
+  "started_at": "2025-01-24T10:00:00Z",
+  "ended_at": "2025-01-24T10:02:30Z",
+  "summary": "Optimization completed successfully"
+}
+```
+
+**Example:**
+```bash
+curl http://localhost:8080/api/v1/status/abc-123-def
+```
+
+---
+
+### 4. List Pending Drafts
+
+Get all pending draft posts that are waiting for review.
+
+```bash
+GET /pending
+```
+
+**Response:**
+```json
+{
+  "count": 5,
+  "records": [
+    {
+      "post_id": 123,
+      "original_post_id": 123,
+      "draft_post_id": 456,
+      "post_title": "How to Test Helm Charts in Production",
+      "language": "en",
+      "optimized_at": "2025-01-24T10:00:00Z",
+      "status": "pending",
+      "optimization": {
+        "seo_meta": {
+          "title": "Ultimate Guide: Testing Helm Charts in Production 2025",
+          "description": "Learn production-grade Helm chart testing with kubeconform, chart-testing, and security scanning. Prevent outages with this complete guide."
+        },
+        "content_optimization": {
+          "changes": [...],
+          "internal_links": [...]
+        },
+        "faq_block": {
+          "should_create": true,
+          "questions": [...]
+        }
+      }
+    }
+  ]
+}
+```
+
+**Example:**
+```bash
+curl http://localhost:8080/api/v1/pending
+```
+
+---
+
+### 5. Get Optimization Details
+
+Get detailed optimization information for a specific post.
+
+```bash
+GET /optimization/{post_id}
+```
+
+**Parameters:**
+- `post_id` (int): Original WordPress post ID
+
+**Response:**
+```json
+{
+  "post_id": 123,
+  "original_post_id": 123,
+  "draft_post_id": 456,
+  "post_title": "How to Test Helm Charts in Production",
+  "language": "en",
+  "optimized_at": "2025-01-24T10:00:00Z",
+  "status": "pending",
+  "optimization": {
+    "seo_meta": {...},
+    "content_optimization": {...},
+    "faq_block": {...},
+    "validation": {...},
+    "summary": "Enhanced SEO with 8 keyword injections..."
+  }
+}
+```
+
+**Example:**
+```bash
+curl http://localhost:8080/api/v1/optimization/123
+```
+
+---
+
+### 6. Apply Draft
+
+Apply a pending draft to the original published post and delete the draft.
+
+```bash
+POST /apply-draft
+Content-Type: application/json
+
+{
+  "draft_post_id": 456
+}
+```
+
+**Parameters:**
+- `draft_post_id` (int, required): WordPress draft post ID to apply
+
+**Response:**
+```json
+{
+  "status": "applied",
+  "message": "Draft applied to original post and draft deleted"
+}
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080/api/v1/apply-draft \
+  -H "Content-Type: application/json" \
+  -d '{"draft_post_id": 456}'
+```
+
+Or use the helper script:
+```bash
+./scripts/apply-draft.sh 456
+```
+
+---
+
+## Workflow
+
+### Typical Optimization Workflow
+
+1. **Trigger Optimization** (automatic via scheduler or manual via API)
+   ```bash
+   POST /optimize {"post_id": 123, "language": "en"}
+   ```
+   - Creates a draft copy with optimized content
+   - Original post stays published
+   - Optimization record saved to storage
+
+2. **Review Pending Drafts**
+   ```bash
+   GET /pending
+   ```
+   - Lists all draft posts waiting for review
+   - Shows what changes were made
+
+3. **Check Optimization Details** (optional)
+   ```bash
+   GET /optimization/123
+   ```
+   - See detailed changes, FAQ blocks, internal links, etc.
+
+4. **Review in WordPress Admin**
+   - Go to Posts → Drafts
+   - Find the draft post (linked to original via meta)
+   - Review changes in WordPress editor
+
+5. **Apply Draft** (when satisfied)
+   ```bash
+   POST /apply-draft {"draft_post_id": 456}
+   ```
+   - Copies draft content to original post
+   - Keeps original post published
+   - Deletes the draft
+   - Updates storage status to "applied"
+
+---
+
+## Error Responses
+
+All endpoints return appropriate HTTP status codes:
+
+- `200 OK`: Success
+- `202 Accepted`: Request accepted (async processing)
+- `400 Bad Request`: Invalid input
+- `404 Not Found`: Resource not found
+- `500 Internal Server Error`: Server error
+
+Error response format:
+```
+HTTP/1.1 400 Bad Request
+post_id must be positive
+```
+
+---
+
+## File Storage
+
+Optimization records are stored in the file system at the configured `storage.base_path`:
+
+```
+./data/optimizations/
+├── pending/       # Drafts waiting for review
+│   ├── 123_1737715200.json
+│   └── 456_1737718800.json
+├── applied/       # Successfully applied optimizations
+│   └── 789_1737629200.json
+└── rejected/      # Manually rejected drafts
+```
+
+Each file contains the complete optimization record including:
+- Post metadata
+- Optimization details
+- SEO meta
+- Content changes
+- FAQ blocks
+- Internal links
+- Validation results
+
+---
+
+## Configuration
+
+Enable/disable the API server in `config.yaml`:
+
+```yaml
+api:
+  enabled: true
+  port: 8080
+
+storage:
+  base_path: "./data/optimizations"
+```
+
+---
+
+## Security
+
+**IMPORTANT**: The API has no authentication and is intended for local access only.
+
+- Do not expose the API to the internet
+- Use a reverse proxy with authentication if needed
+- Run on localhost or behind a firewall
+
+---
+
+## Monitoring
+
+Check server logs for detailed operation information:
+
+```bash
+# View logs in JSON format
+tail -f logs/optimizer.log | jq
+
+# Filter for API-related logs
+tail -f logs/optimizer.log | jq 'select(.component == "api")'
+```