Munich-news/docs/API.md

# API Reference

Complete API documentation for Munich News Daily.

---

## Admin API

Base URL: `http://localhost:5001`

### Trigger Crawler

Manually fetch new articles.

```http
POST /api/admin/trigger-crawl
Content-Type: application/json

{
  "max_articles": 10
}
```

**Example:**
```bash
curl -X POST http://localhost:5001/api/admin/trigger-crawl \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 5}'
```

---

### Send Test Email

Send newsletter to specific email.

```http
POST /api/admin/send-test-email
Content-Type: application/json

{
  "email": "test@example.com",
  "max_articles": 10
}
```

**Example:**
```bash
curl -X POST http://localhost:5001/api/admin/send-test-email \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com"}'
```

---

### Send Newsletter to All Subscribers

Send newsletter to all active subscribers.

```http
POST /api/admin/send-newsletter
Content-Type: application/json

{
  "max_articles": 10
}
```

**Response:**
```json
{
  "success": true,
  "message": "Newsletter sent successfully to 45 subscribers",
  "subscriber_count": 45,
  "max_articles": 10
}
```

**Example:**
```bash
curl -X POST http://localhost:5001/api/admin/send-newsletter \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 10}'
```

---

### Get System Stats

```http
GET /api/admin/stats
```

**Response:**
```json
{
  "articles": {
    "total": 150,
    "with_summary": 120,
    "today": 15
  },
  "subscribers": {
    "total": 50,
    "active": 45
  },
  "rss_feeds": {
    "total": 4,
    "active": 4
  },
  "tracking": {
    "total_sends": 200,
    "total_opens": 150,
    "total_clicks": 75
  }
}
```

**Example:**
```bash
curl http://localhost:5001/api/admin/stats
```

---

## Public API

### Subscribe

```http
POST /api/subscribe
Content-Type: application/json

{
  "email": "user@example.com"
}
```

**Example:**
```bash
curl -X POST http://localhost:5001/api/subscribe \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

---

### Unsubscribe

```http
POST /api/unsubscribe
Content-Type: application/json

{
  "email": "user@example.com"
}
```

**Example:**
```bash
curl -X POST http://localhost:5001/api/unsubscribe \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

---

## Subscriber Status System

### Status Values

| Status | Description | Receives Newsletters |
|--------|-------------|---------------------|
| `active` | Subscribed | ✅ Yes |
| `inactive` | Unsubscribed | ❌ No |

### Database Schema

```javascript
{
  _id: ObjectId("..."),
  email: "user@example.com",
  subscribed_at: ISODate("2025-11-11T15:50:29.478Z"),
  status: "active"  // or "inactive"
}
```

### How It Works

**Subscribe:**
- Creates subscriber with `status: 'active'`
- If already exists and inactive, reactivates

**Unsubscribe:**
- Updates `status: 'inactive'`
- Subscriber data preserved (soft delete)

**Newsletter Sending:**
- Only sends to `status: 'active'` subscribers
- Query: `{status: 'active'}`

### Check Active Subscribers

```bash
curl http://localhost:5001/api/admin/stats | jq '.subscribers'
# Output: {"total": 10, "active": 8}
```

---

## Workflows

### Complete Newsletter Workflow

```bash
# 1. Check stats
curl http://localhost:5001/api/admin/stats

# 2. Crawl articles
curl -X POST http://localhost:5001/api/admin/trigger-crawl \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 10}'

# 3. Wait for crawl
sleep 60

# 4. Send newsletter
curl -X POST http://localhost:5001/api/admin/send-newsletter \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 10}'
```

### Test Newsletter

```bash
# Send test to yourself
curl -X POST http://localhost:5001/api/admin/send-test-email \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "max_articles": 3}'
```

---

## Error Responses

All endpoints return standard error format:

```json
{
  "success": false,
  "error": "Error message here"
}
```

**HTTP Status Codes:**
- `200` - Success
- `400` - Bad request
- `404` - Not found
- `500` - Server error

---

## Security

⚠️ **Production Recommendations:**

1. **Add Authentication**
   ```python
   @require_api_key
   def admin_endpoint():
       # ...
   ```

2. **Rate Limiting**
   - Prevent abuse
   - Limit newsletter sends

3. **IP Whitelisting**
   - Restrict admin endpoints
   - Use firewall rules

4. **HTTPS Only**
   - Use reverse proxy
   - SSL/TLS certificates

5. **Audit Logging**
   - Log all admin actions
   - Monitor for suspicious activity

---

## Testing

Use the test script:
```bash
./test-newsletter-api.sh
```

Or test manually:
```bash
# Health check
curl http://localhost:5001/health

# Stats
curl http://localhost:5001/api/admin/stats

# Test email
curl -X POST http://localhost:5001/api/admin/send-test-email \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'
```

---

See [SETUP.md](SETUP.md) for configuration and [SECURITY.md](SECURITY.md) for security best practices.