515 lines
8.4 KiB
Markdown
515 lines
8.4 KiB
Markdown
# 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
|
|
```
|
|
|
|
---
|
|
|
|
### 7. Get Draft Content
|
|
|
|
Fetch draft content for CLI-friendly review.
|
|
|
|
```bash
|
|
GET /drafts/{draft_post_id}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": 456,
|
|
"status": "draft",
|
|
"title": "Draft title",
|
|
"excerpt": "Draft excerpt",
|
|
"content": "<p>Rendered HTML...</p>"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 8. Ideas: List
|
|
|
|
List stored idea records by status.
|
|
|
|
```bash
|
|
GET /ideas?status=new
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"count": 3,
|
|
"ideas": [
|
|
{
|
|
"id": "uuid",
|
|
"seo_title": "Kubernetes Pod Security Standards: What Changed in 2025",
|
|
"summary": "Idea summary...",
|
|
"status": "new",
|
|
"created_at": "2026-01-25T09:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 9. Ideas: Generate Now
|
|
|
|
Trigger idea generation from Reddit immediately.
|
|
|
|
```bash
|
|
POST /ideas/generate
|
|
```
|
|
|
|
---
|
|
|
|
### 10. Ideas: Generate Drafts
|
|
|
|
Generate full English + Spanish drafts for an idea.
|
|
|
|
```bash
|
|
POST /ideas/{id}/draft
|
|
```
|
|
|
|
---
|
|
|
|
### 11. Ideas: Publish Drafts
|
|
|
|
Publish the drafts created for an idea.
|
|
|
|
```bash
|
|
POST /ideas/{id}/publish
|
|
```
|
|
|
|
---
|
|
|
|
### 12. Ideas: Delete
|
|
|
|
Delete an idea record (and any drafts created from it).
|
|
|
|
```bash
|
|
POST /ideas/{id}/delete
|
|
```
|
|
|
|
---
|
|
|
|
### 13. Outreach: List
|
|
|
|
List outreach suggestions.
|
|
|
|
```bash
|
|
GET /outreach?status=new
|
|
```
|
|
|
|
---
|
|
|
|
### 14. Outreach: Generate Now
|
|
|
|
Generate outreach suggestions from Reddit now.
|
|
|
|
```bash
|
|
POST /outreach/generate
|
|
```
|
|
|
|
---
|
|
|
|
### 15. Outreach: Delete
|
|
|
|
Delete an outreach suggestion.
|
|
|
|
```bash
|
|
POST /outreach/{id}/delete
|
|
```
|
|
|
|
---
|
|
|
|
### 16. Newsletter: List
|
|
|
|
List newsletter drafts.
|
|
|
|
```bash
|
|
GET /newsletter?status=draft
|
|
```
|
|
|
|
---
|
|
|
|
### 17. Newsletter: Generate Now
|
|
|
|
Generate a newsletter draft from RSS + Reddit.
|
|
|
|
```bash
|
|
POST /newsletter/generate
|
|
```
|
|
|
|
---
|
|
|
|
### 18. Newsletter: Delete
|
|
|
|
Delete a newsletter draft.
|
|
|
|
```bash
|
|
POST /newsletter/{id}/delete
|
|
```
|
|
|
|
## 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
|
|
|
|
---
|
|
|
|
## Audit Log
|
|
|
|
List recent actions recorded by the system (CLI/WebUI/API).
|
|
|
|
```bash
|
|
GET /audit?limit=100
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"count": 2,
|
|
"records": [
|
|
{
|
|
"id": "uuid-string",
|
|
"created_at": "2025-01-24T10:05:00Z",
|
|
"actor": "cli",
|
|
"action": "draft_applied",
|
|
"summary": "Applied draft 456 to original post 123",
|
|
"post_id": 123,
|
|
"draft_post_id": 456
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Audit records are stored at the configured `audit.base_path`.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Enable/disable the API server in `config.yaml`:
|
|
|
|
```yaml
|
|
api:
|
|
enabled: true
|
|
port: 8080
|
|
|
|
storage:
|
|
base_path: "./data/optimizations"
|
|
|
|
audit:
|
|
base_path: "./data/audit"
|
|
```
|
|
|
|
---
|
|
|
|
## 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")'
|
|
```
|