blackroad-operating-system/API_INTEGRATIONS.md

Multi-API Integration Guide

BlackRoad Operating System now supports comprehensive API integrations for deployment, payments, communications, monitoring, and more.

🚀 Deployment Platforms

Railway

GraphQL API for cloud deployments

• Endpoints: /api/railway/*
• Configuration: RAILWAY_TOKEN
• Features:
  • List and manage projects
  • View deployments and services
  • Trigger new deployments
  • Manage environment variables
• Docs: https://docs.railway.app/reference/public-api

Vercel

REST API for serverless deployments

• Endpoints: /api/vercel/*
• Configuration: VERCEL_TOKEN, VERCEL_TEAM_ID (optional)
• Features:
  • Manage projects and deployments
  • Configure custom domains
  • Set environment variables
  • Monitor deployment status
• Docs: https://vercel.com/docs/rest-api

💳 Payment Processing

Stripe

Payment processing and billing

• Endpoints: /api/stripe/*
• Configuration: STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY
• Features:
  • Create payment intents
  • Manage customers
  • Handle subscriptions
  • View account balance
• Docs: https://stripe.com/docs/api

📱 Communications

Twilio

SMS, Voice, and WhatsApp messaging

• Endpoints: /api/twilio/*
• Configuration: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER
• Features:
  • Send SMS messages
  • Send WhatsApp messages
  • Track message status
  • View message history
• Docs: https://www.twilio.com/docs/usage/api

Slack

Team collaboration and notifications

• Endpoints: /api/slack/*
• Configuration: SLACK_BOT_TOKEN, SLACK_WEBHOOK_URL (optional)
• Features:
  • Post messages to channels
  • List channels
  • Send webhook notifications
  • Get user information
• Docs: https://api.slack.com/

Discord

Community messaging and notifications

• Endpoints: /api/discord/*
• Configuration: DISCORD_BOT_TOKEN, DISCORD_WEBHOOK_URL (optional)
• Features:
  • Send messages to channels
  • Manage guild/server information
  • Send webhook notifications
  • Get user details
• Docs: https://discord.com/developers/docs/intro

🔍 Monitoring & Error Tracking

Sentry

Application monitoring and error tracking

• Endpoints: /api/sentry/*
• Configuration: SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_DSN
• Features:
  • View error issues
  • Track events
  • Manage releases
  • Get project statistics
• Docs: https://docs.sentry.io/api/

🏥 Health Monitoring

Centralized API Health Check

Monitor all API connections in one place

• Endpoints:

  • /api/health/all - Comprehensive health check for all APIs
  • /api/health/summary - Quick summary of API status
  • /api/health/{api_name} - Check specific API (e.g., /api/health/railway)

• Response Example:

{
  "status": "healthy",
  "total_apis": 12,
  "connected_apis": 8,
  "not_configured_apis": 3,
  "error_apis": 1,
  "apis": {
    "railway": {
      "name": "railway",
      "status": "connected",
      "message": "Railway API connected successfully",
      "last_checked": "2025-01-16T12:00:00Z"
    }
  }
}

🔧 Configuration

Environment Variables

All API integrations require environment variables. Copy .env.example to .env and configure:

# Deployment Platforms
RAILWAY_TOKEN=your-railway-api-token
VERCEL_TOKEN=your-vercel-api-token
VERCEL_TEAM_ID=your-team-id  # Optional

# Payments
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...

# Communications
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1234567890

SLACK_BOT_TOKEN=xoxb-...
SLACK_WEBHOOK_URL=https://hooks.slack.com/...

DISCORD_BOT_TOKEN=...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Monitoring
SENTRY_DSN=https://...@sentry.io/...
SENTRY_AUTH_TOKEN=...
SENTRY_ORG=your-org-slug

Quick Setup

1. Install dependencies:

   cd backend
   pip install -r requirements.txt
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your API keys
   

3. Start the server:

   python run.py
   

4. Check API health:

   curl http://localhost:8000/api/health/summary
   

📖 API Documentation

Once the server is running, access interactive documentation:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• OpenAPI Schema: http://localhost:8000/api/openapi.json

🧪 Testing

Run all tests:

cd backend
pytest -v

Run API integration tests:

pytest tests/test_api_integrations.py -v

Test specific API:

pytest tests/test_api_integrations.py::TestRailwayAPI -v

🚢 Deployment

Railway

1. Install Railway CLI: curl -fsSL https://railway.app/install.sh | sh
2. Login: railway login
3. Deploy: railway up

Configuration files:

• railway.json - Railway build configuration
• railway.toml - Railway deployment settings

GitHub Actions

Automated workflows are configured in .github/workflows/:

• backend-tests.yml - Run tests and check API connectivity
• railway-deploy.yml - Deploy to Railway on push to main

🔑 Getting API Keys

Railway

1. Go to https://railway.app
2. Create account → Settings → Tokens → Create Token

Vercel

1. Go to https://vercel.com
2. Settings → Tokens → Create Token

Stripe

1. Go to https://dashboard.stripe.com
2. Developers → API Keys → Create Key

Twilio

1. Go to https://www.twilio.com/console
2. Get Account SID and Auth Token

Slack

1. Go to https://api.slack.com/apps
2. Create App → OAuth & Permissions → Bot Token

Discord

1. Go to https://discord.com/developers/applications
2. Create Application → Bot → Copy Token

Sentry

1. Go to https://sentry.io
2. Settings → Auth Tokens → Create Token

📊 Monitoring Best Practices

1. Use health checks: Monitor /api/health/all endpoint
2. Set up webhooks: Configure Slack/Discord for deployment notifications
3. Enable Sentry: Track errors in production
4. Monitor API quotas: Check usage limits for each service

🛡️ Security

• Never commit API keys: Use .env files (gitignored)
• Rotate keys regularly: Update credentials periodically
• Use environment-specific keys: Different keys for dev/staging/prod
• Monitor API usage: Watch for unusual activity

🤝 Support

For issues or questions:

• Check logs: docker-compose logs backend
• API documentation: /api/docs
• Health status: /api/health/summary

📝 License

Part of BlackRoad Operating System - See main README for license information.