Skip to content

API

Jump to bottom
Pakrohk edited this page Dec 9, 2025 · 1 revision

📚 API Reference

Complete API documentation for RssBot Platform's REST endpoints, service management, and integration capabilities.

🎯 API Overview

RssBot Platform provides a comprehensive REST API for:

  • 🎛️ Service Management: Configure connection methods, health monitoring
  • 🗄️ Database Operations: Feed management, user data, analytics
  • 🤖 Bot Operations: Message handling, subscription management
  • 🧠 AI Processing: Content enhancement, summarization
  • 💳 Payment Processing: Subscription management, billing
  • ⚙️ Admin Operations: Platform configuration, monitoring

🔗 Base URLs

Environment Base URL Description
Development http://localhost:8004 Local development
Staging https://staging-api.yourdomain.com Staging environment
Production https://api.yourdomain.com Production API

🔐 Authentication

Service Token Authentication

All API requests require a service token in the header:

curl -H "Authorization: Bearer your_service_token_here" \
     -H "Content-Type: application/json" \
     http://localhost:8004/api/endpoint

Admin API Key

Admin endpoints require an additional API key:

curl -H "X-API-Key: your_admin_api_key" \
     -H "Authorization: Bearer your_service_token" \
     http://localhost:8004/admin/endpoint

🎛️ Core Platform APIs

Health & Status

GET /health

Get overall platform health status.

curl http://localhost:8004/health

Response:

{
  "status": "healthy",
  "architecture": "per_service_core_controller",
  "services_count": 6,
  "database_status": "connected",
  "cache_status": "connected",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

GET /services

List all registered services and their status.

curl http://localhost:8004/services

Response:

[
  {
    "name": "db_svc",
    "status": "running",
    "connection_method": "router",
    "health_score": 0.95,
    "last_seen": "2024-01-15T10:29:45Z",
    "port": 8001,
    "url": "http://localhost:8001"
  },
  {
    "name": "ai_svc",
    "status": "running", 
    "connection_method": "hybrid",
    "health_score": 0.88,
    "last_seen": "2024-01-15T10:29:50Z",
    "port": 8003
  }
]

Service Management

POST /services/{service_name}/connection-method

Change a service's connection method.

Request:

curl -X POST http://localhost:8004/services/ai_svc/connection-method \
  -H "Content-Type: application/json" \
  -d '{"connection_method": "router"}'

Parameters:

  • connection_method: "router", "rest", "hybrid", or "disabled"

Response:

{
  "service_name": "ai_svc",
  "old_method": "rest",
  "new_method": "router",
  "changed_at": "2024-01-15T10:30:00Z",
  "status": "updated"
}

GET /services/{service_name}/status

Get detailed status for a specific service.

curl http://localhost:8004/services/ai_svc/status

Response:

{
  "name": "ai_svc",
  "status": "running",
  "connection_method": "hybrid",
  "health": {
    "score": 0.88,
    "latency_ms": 45,
    "success_rate": 0.97,
    "last_check": "2024-01-15T10:29:50Z"
  },
  "metrics": {
    "requests_total": 1547,
    "errors_total": 23,
    "avg_response_time_ms": 234
  },
  "configuration": {
    "max_tokens": 1000,
    "model": "gpt-3.5-turbo",
    "temperature": 0.7
  }
}

🗄️ Database Service APIs

Feed Management

GET /services/db_svc/feeds

List all RSS feeds.

curl http://localhost:8004/services/db_svc/feeds

Query Parameters:

  • limit (optional): Maximum number of feeds to return (default: 50)
  • offset (optional): Number of feeds to skip (default: 0)
  • active_only (optional): Only return active feeds (default: false)

Response:

{
  "feeds": [
    {
      "id": 1,
      "url": "https://feeds.feedburner.com/oreilly",
      "title": "O'Reilly Media",
      "description": "Technology and business insights",
      "last_updated": "2024-01-15T10:25:00Z",
      "active": true,
      "chat_id": -1001234567890,
      "subscribers_count": 156
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

POST /services/db_svc/feeds

Create a new RSS feed.

Request:

curl -X POST http://localhost:8004/services/db_svc/feeds \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/rss.xml",
    "title": "Example Feed",
    "chat_id": -1001234567890,
    "update_interval": 3600
  }'

Response:

{
  "id": 2,
  "url": "https://example.com/rss.xml",
  "title": "Example Feed", 
  "chat_id": -1001234567890,
  "update_interval": 3600,
  "active": true,
  "created_at": "2024-01-15T10:35:00Z"
}

PUT /services/db_svc/feeds/{feed_id}

Update an existing RSS feed.

Request:

curl -X PUT http://localhost:8004/services/db_svc/feeds/2 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Feed Title",
    "active": false
  }'

DELETE /services/db_svc/feeds/{feed_id}

Delete an RSS feed.

curl -X DELETE http://localhost:8004/services/db_svc/feeds/2

User Management

GET /services/db_svc/users

List all users.

curl http://localhost:8004/services/db_svc/users?limit=20&offset=0

POST /services/db_svc/users

Create or update a user.

Request:

curl -X POST http://localhost:8004/services/db_svc/users \
  -H "Content-Type: application/json" \
  -d '{
    "telegram_id": 123456789,
    "username": "johndoe",
    "first_name": "John",
    "subscription_type": "free"
  }'

🤖 Bot Service APIs

Message Operations

POST /services/bot_svc/send-message

Send a message to a Telegram chat.

Request:

curl -X POST http://localhost:8004/services/bot_svc/send-message \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": -1001234567890,
    "text": "Hello from RssBot!",
    "parse_mode": "HTML"
  }'

Response:

{
  "message_id": 12345,
  "chat_id": -1001234567890,
  "sent_at": "2024-01-15T10:40:00Z",
  "status": "sent"
}

POST /services/bot_svc/broadcast

Broadcast a message to multiple chats.

Request:

curl -X POST http://localhost:8004/services/bot_svc/broadcast \
  -H "Content-Type: application/json" \
  -d '{
    "chat_ids": [-1001234567890, -1001234567891],
    "text": "RSS Feed Update!",
    "parse_mode": "HTML"
  }'

Webhook Management

POST /services/bot_svc/set-webhook

Configure Telegram webhook.

Request:

curl -X POST http://localhost:8004/services/bot_svc/set-webhook \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourdomain.com/webhook",
    "secret_token": "your_webhook_secret"
  }'

DELETE /services/bot_svc/webhook

Remove Telegram webhook (switch to polling).

curl -X DELETE http://localhost:8004/services/bot_svc/webhook

🧠 AI Service APIs

Content Processing

POST /services/ai_svc/summarize

Summarize content using AI.

Request:

curl -X POST http://localhost:8004/services/ai_svc/summarize \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Long article content here...",
    "max_length": 200,
    "language": "en"
  }'

Response:

{
  "original_text": "Long article content here...",
  "summary": "Brief summary of the article...",
  "summary_length": 45,
  "processing_time_ms": 1250,
  "model_used": "gpt-3.5-turbo"
}

POST /services/ai_svc/enhance

Enhance content with AI.

Request:

curl -X POST http://localhost:8004/services/ai_svc/enhance \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Original content",
    "enhancement_type": "readability",
    "target_audience": "general"
  }'

POST /services/ai_svc/translate

Translate content to another language.

Request:

curl -X POST http://localhost:8004/services/ai_svc/translate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world",
    "target_language": "es",
    "source_language": "en"
  }'

💳 Payment Service APIs

Subscription Management

GET /services/payment_svc/subscriptions

List user subscriptions.

curl http://localhost:8004/services/payment_svc/subscriptions?user_id=123456789

POST /services/payment_svc/create-checkout

Create a Stripe checkout session.

Request:

curl -X POST http://localhost:8004/services/payment_svc/create-checkout \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123456789,
    "price_id": "price_premium_plan",
    "success_url": "https://yourdomain.com/success",
    "cancel_url": "https://yourdomain.com/cancel"
  }'

Response:

{
  "checkout_url": "https://checkout.stripe.com/pay/cs_test_...",
  "session_id": "cs_test_1234567890",
  "expires_at": "2024-01-15T11:40:00Z"
}

⚙️ Admin APIs

Platform Configuration

GET /admin/config

Get current platform configuration.

curl -H "X-API-Key: your_admin_key" \
     http://localhost:8004/admin/config

POST /admin/config/reload

Reload platform configuration without restart.

curl -X POST -H "X-API-Key: your_admin_key" \
     http://localhost:8004/admin/config/reload

Monitoring & Metrics

GET /admin/metrics

Get platform performance metrics.

curl -H "X-API-Key: your_admin_key" \
     http://localhost:8004/admin/metrics

Response:

{
  "platform": {
    "uptime_seconds": 86400,
    "requests_total": 15476,
    "errors_total": 23,
    "avg_response_time_ms": 45
  },
  "services": {
    "db_svc": {
      "requests": 8234,
      "errors": 5,
      "avg_response_time_ms": 12
    },
    "ai_svc": {
      "requests": 1245,
      "errors": 8,
      "avg_response_time_ms": 234
    }
  },
  "cache": {
    "hit_rate": 0.87,
    "total_hits": 13463,
    "total_misses": 2013
  }
}

GET /admin/logs/{service_name}

Get logs for a specific service.

curl -H "X-API-Key: your_admin_key" \
     "http://localhost:8004/admin/logs/ai_svc?limit=100&level=ERROR"

🚨 Error Handling

Standard Error Response

All APIs return consistent error responses:

{
  "error": {
    "code": "SERVICE_NOT_FOUND",
    "message": "Service 'unknown_svc' not found",
    "details": {
      "service_name": "unknown_svc",
      "available_services": ["db_svc", "ai_svc", "bot_svc"]
    },
    "timestamp": "2024-01-15T10:45:00Z",
    "request_id": "req_1234567890"
  }
}

Common Error Codes

Code HTTP Status Description
INVALID_REQUEST 400 Malformed request body or parameters
UNAUTHORIZED 401 Missing or invalid authentication
FORBIDDEN 403 Insufficient permissions
SERVICE_NOT_FOUND 404 Requested service doesn't exist
METHOD_NOT_ALLOWED 405 HTTP method not supported
RATE_LIMIT_EXCEEDED 429 Too many requests
SERVICE_UNAVAILABLE 503 Service temporarily unavailable
INTERNAL_ERROR 500 Unexpected server error

📊 Rate Limiting

Rate Limit Headers

All API responses include rate limiting information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642234800
X-RateLimit-Window: 3600

Rate Limits by Endpoint Type

Endpoint Type Rate Limit Window
Health/Status 100 req/min Per IP
Service Management 50 req/min Per API key
Database Operations 200 req/min Per API key
AI Processing 60 req/min Per API key
Admin Operations 30 req/min Per API key

🔧 SDK and Libraries

Python SDK

from rssbot_client import RssBotClient

client = RssBotClient(
    base_url="http://localhost:8004",
    service_token="your_service_token"
)

# Get platform health
health = await client.get_health()

# Manage services
await client.set_connection_method("ai_svc", "hybrid")

# Send messages
await client.send_message(
    chat_id=-1001234567890,
    text="Hello from Python!"
)

JavaScript SDK

import { RssBotClient } from '@rssbot/client';

const client = new RssBotClient({
  baseUrl: 'http://localhost:8004',
  serviceToken: 'your_service_token'
});

// Get services
const services = await client.getServices();

// Process with AI
const summary = await client.ai.summarize({
  text: 'Long content...',
  maxLength: 200
});

📚 This API reference covers all major endpoints. For interactive API exploration, visit /docs on your running platform instance.

📚 RssBot Platform Wiki

🏠 Home

🏁 Getting Started

🏗️ Architecture & Design

👨‍💻 Development

🚀 Deployment & Ops

🔒 Security

🛠️ Advanced

🇮🇷 مستندات فارسی

شروع کار

معماری

Clone this wiki locally