Skip to content

admin.md

Latest commit

 

History

History
246 lines (186 loc) · 5.45 KB

admin.md

File metadata and controls

246 lines (186 loc) · 5.45 KB
Raw

📧 Newsletter Admin API Reference

This document provides comprehensive examples for testing the PostgreSQL-powered newsletter admin API using cURL commands.

🔑 Authentication

All admin endpoints require the x-api-key header:

x-api-key: kodalabs-admin-secure-2024

🌐 Base URLs

Local Development:

http://localhost:3000

Production (VPS):

https://kodalabs.dev

📊 Admin Statistics

Get comprehensive subscriber statistics including total count, retention rates, language distribution, and growth metrics.

Local Development

curl -H "x-api-key: kodalabs-admin-secure-2024" \
     -H "Content-Type: application/json" \
     "http://localhost:3000/api/admin/stats"

Production

curl -H "x-api-key: kodalabs-admin-secure-2024" \
     -H "Content-Type: application/json" \
     "https://kodalabs.dev/api/admin/stats"

Expected Response

{
  "overview": {
    "total_subscribers": 7,
    "active_subscribers": 7,
    "retention_rate": "100.00%",
    "recent_subscribers": 0,
    "portuguese_subscribers": 4,
    "english_subscribers": 2,
    "spanish_subscribers": 1
  },
  "growth": {
    "total_growth": 7
  },
  "sources": [
    {
      "source": "newsletter_form",
      "count": "7",
      "active_count": "7"
    }
  ]
}

👥 Subscriber List (JSON)

Get all subscribers in JSON format with detailed information.

Local Development

curl -H "x-api-key: kodalabs-admin-secure-2024" \
     -H "Content-Type: application/json" \
     "http://localhost:3000/api/admin/subscribers"

Production

curl -H "x-api-key: kodalabs-admin-secure-2024" \
     -H "Content-Type: application/json" \
     "https://kodalabs.dev/api/admin/subscribers"

With Query Parameters

# Get only active subscribers
curl -H "x-api-key: kodalabs-admin-secure-2024" \
     "http://localhost:3000/api/admin/subscribers?active_only=true"

# Limit results
curl -H "x-api-key: kodalabs-admin-secure-2024" \
     "http://localhost:3000/api/admin/subscribers?limit=10"

📥 CSV Export

Export subscriber data as CSV file for spreadsheet analysis.

Local Development

curl -H "x-api-key: kodalabs-admin-secure-2024" \
     "http://localhost:3000/api/admin/subscribers?format=csv" \
     -o "subscribers-$(date +%Y-%m-%d).csv"

Production

curl -H "x-api-key: kodalabs-admin-secure-2024" \
     "https://kodalabs.dev/api/admin/subscribers?format=csv" \
     -o "subscribers-$(date +%Y-%m-%d).csv"

CSV Headers

email,name,locale,source,subscribed_at,status,metadata

🔍 Individual Subscriber Lookup

Get details for a specific subscriber by email address.

Local Development

curl -H "x-api-key: kodalabs-admin-secure-2024" \
     "http://localhost:3000/api/admin/subscribers/user%40example.com"

Production

curl -H "x-api-key: kodalabs-admin-secure-2024" \
     "https://kodalabs.dev/api/admin/subscribers/user%40example.com"

Note: Email addresses must be URL-encoded (@ becomes %40)

🏥 Health Check

Basic endpoint to test API connectivity (no authentication required).

Local Development

curl "http://localhost:3000/api/admin/health"

Production

curl "https://kodalabs.dev/api/admin/health"

🚫 Authentication Testing

Test authentication by making requests without the API key (should return 401).

# This should fail with 401 Unauthorized
curl -H "Content-Type: application/json" \
     "http://localhost:3000/api/admin/stats"

Expected error response:

{
  "error": "Missing API key"
}

🔧 Troubleshooting

Common Issues

  1. 401 Unauthorized

    • Missing x-api-key header
    • Incorrect API key value
    • Check: kodalabs-admin-secure-2024

  2. 404 Not Found

    • Incorrect endpoint URL
    • Next.js server not running
    • Check base URL: http://localhost:3000

  3. Connection Refused

    • Next.js development server not started
    • Run: npm run dev
    • PostgreSQL container not running
    • Run: docker-compose -f docker-compose.local.yml up -d

Debug Commands

# Check if Next.js server is running
curl -I "http://localhost:3000"

# Check PostgreSQL container
docker ps | grep postgres

# Test basic API connectivity
curl "http://localhost:3000/api/health"

🌍 Production Deployment Notes

When deploying to your VPS:

  1. Update Base URLs - Change from localhost:3000 to your production domain
  2. Environment Variables - Ensure ADMIN_API_KEY is set in production
  3. PostgreSQL Connection - Update DATABASE_URL for production database
  4. SSL/HTTPS - Use https:// URLs for production requests
  5. Firewall - Ensure API endpoints are accessible

Production Environment Variables

DATABASE_URL=postgresql://user:pass@prod-db:5432/kodalabs
ADMIN_API_KEY=kodalabs-admin-secure-2024
NEXT_PUBLIC_SITE_URL=https://kodalabs.dev

📖 API Endpoint Summary

Endpoint Method Auth Required Description
/api/admin/health GET ❌ Basic connectivity test
/api/admin/stats GET ✅ Subscriber statistics
/api/admin/subscribers GET ✅ List all subscribers (JSON)
/api/admin/subscribers?format=csv GET ✅ Export subscribers (CSV)
/api/admin/subscribers/[email] GET ✅ Individual subscriber lookup

Authentication Header: x-api-key: kodalabs-admin-secure-2024