8000
Skip to content

API.md

Latest commit

 

History

History
494 lines (426 loc) · 8.67 KB

API.md

File metadata and controls

494 lines (426 loc) · 8.67 KB

Ofelia API Documentation

Overview

Ofelia provides a RESTful API for job management, monitoring, and configuration. All API endpoints are available when the web UI is enabled with --enable-web.

Authentication

JWT Authentication

The API uses JWT tokens for authentication when security is enabled.

Login

POST /api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "secret"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2024-01-01T00:00:00Z"
}

Using the Token

Include the JWT token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Refresh Token

POST /api/refresh
Authorization: Bearer <current-token>

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2024-01-01T00:00:00Z"
}

Job Management

List All Jobs

GET /api/jobs

Response:

{
  "jobs": [
    {
      "name": "backup",
      "type": "exec",
      "schedule": "@daily",
      "command": "backup.sh",
      "container": "myapp",
      "lastRun": "2024-01-01T00:00:00Z",
      "nextRun": "2024-01-02T00:00:00Z",
      "status": "success",
      "origin": "config",
      "enabled": true
    },
    {
      "name": "cleanup",
      "type": "run",
      "schedule": "0 2 * * *",
      "image": "alpine:latest",
      "command": "cleanup.sh",
      "lastRun": "2024-01-01T02:00:00Z",
      "nextRun": "2024-01-02T02:00:00Z",
      "status": "running",
      "origin": "docker-label",
      "enabled": true
    }
  ],
  "total": 2,
  "running": 1
}

Get Job Details

GET /api/job/{name}

Response:

{
  "name": "backup",
  "type": "exec",
  "schedule": "@daily",
  "command": "backup.sh",
  "container": "myapp",
  "user": "nobody",
  "environment": ["BACKUP_DIR=/data"],
  "tty": false,
  "lastRun": "2024-01-01T00:00:00Z",
  "nextRun": "2024-01-02T00:00:00Z",
  "status": "success",
  "origin": "config",
  "enabled": true,
  "history": [
    {
      "executionId": "550e8400-e29b-41d4-a716-446655440000",
      "startTime": "2024-01-01T00:00:00Z",
      "endTime": "2024-01-01T00:05:00Z",
      "duration": 300000000000,
      "status": "success",
      "output": "Backup completed successfully",
      "error": null
    }
  ],
  "metrics": {
    "totalRuns": 30,
    "successfulRuns": 29,
    "failedRuns": 1,
    "averageDuration": 285000000000,
    "lastSuccess": "2024-01-01T00:00:00Z",
    "lastFailure": "2023-12-15T00:00:00Z"
  }
}

Trigger Job Execution

POST /api/job/{name}/run

Response:

{
  "executionId": "550e8400-e29b-41d4-a716-446655440001",
  "job": "backup",
  "startTime": "2024-01-01T12:00:00Z",
  "status": "running"
}

Update Job Configuration

PUT /api/job/{name}
Content-Type: application/json

{
  "schedule": "0 3 * * *",
  "command": "backup.sh --verbose",
  "environment": ["BACKUP_DIR=/data", "COMPRESSION=gzip"]
}

Response:

{
  "name": "backup",
  "updated": true,
  "message": "Job configuration updated successfully"
}

Delete Job

DELETE /api/job/{name}

Response:

{
  "name": "backup",
  "deleted": true,
  "message": "Job deleted successfully"
}

Enable/Disable Job

PATCH /api/job/{name}/toggle

Response:

{
  "name": "backup",
  "enabled": false,
  "message": "Job disabled"
}

Executio 8000 n Management

Get Execution Status

GET /api/execution/{executionId}

Response:

{
  "executionId": "550e8400-e29b-41d4-a716-446655440001",
  "job": "backup",
  "startTime": "2024-01-01T12:00:00Z",
  "endTime": "2024-01-01T12:05:00Z",
  "duration": 300000000000,
  "status": "success",
  "output": "Backup completed\n1000 files processed",
  "error": null,
  "exitCode": 0
}

Stop Running Execution

POST /api/execution/{executionId}/stop

Response:

{
  "executionId": "550e8400-e29b-41d4-a716-446655440001",
  "stopped": true,
  "message": "Execution stopped"
}

Get Execution Logs

GET /api/execution/{executionId}/logs

Response:

{
  "executionId": "550e8400-e29b-41d4-a716-446655440001",
  "logs": [
    {
      "timestamp": "2024-01-01T12:00:00Z",
      "level": "info",
      "message": "Starting backup process"
    },
    {
      "timestamp": "2024-01-01T12:00:01Z",
      "level": "info",
      "message": "Scanning files..."
    },
    {
      "timestamp": "2024-01-01T12:05:00Z",
      "level": "info",
      "message": "Backup completed successfully"
    }
  ]
}

Scheduler Control

Get Scheduler Status

GET /api/scheduler/status

Response:

{
  "running": true,
  "startTime": "2024-01-01T00:00:00Z",
  "uptime": 86400,
  "totalJobs": 15,
  "activeJobs": 12,
  "runningJobs": 2,
  "nextJob": {
    "name": "cleanup",
    "scheduledTime": "2024-01-02T02:00:00Z"
  }
}

Start/Stop Scheduler

POST /api/scheduler/start
POST /api/scheduler/stop

Response:

{
  "running": true,
  "message": "Scheduler started"
}

Reload Configuration

POST /api/scheduler/reload

Response:

{
  "reloaded": true,
  "jobsAdded": 2,
  "jobsUpdated": 1,
  "jobsRemoved": 0,
  "message": "Configuration reloaded successfully"
}

Monitoring

Health Check

GET /health/liveness

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z"
}

Readiness Check

GET /health/readiness

Response:

{
  "ready": true,
  "scheduler": "running",
  "docker": "connected",
  "database": "n/a"
}

Prometheus Metrics

GET /metrics

Response:

# HELP ofelia_jobs_total Total number of jobs executed
# TYPE ofelia_jobs_total counter
ofelia_jobs_total 1234

# HELP ofelia_jobs_failed_total Total number of failed jobs
# TYPE ofelia_jobs_failed_total counter
ofelia_jobs_failed_total 12

# HELP ofelia_jobs_running Number of currently running jobs
# TYPE ofelia_jobs_running gauge
ofelia_jobs_running 2

# HELP ofelia_job_duration_seconds Job execution duration in seconds
# TYPE ofelia_job_duration_seconds histogram
ofelia_job_duration_seconds_bucket{le="0.1"} 100
ofelia_job_duration_seconds_bucket{le="0.5"} 500
...

Configuration

Get Current Configuration

GET /api/config

Response:

{
  "global": {
    "dockerHost": "unix:///var/run/docker.sock",
    "dockerPollInterval": 30,
    "dockerEvents": true,
    "slackURL": "https://hooks.slack.com/...",
    "emailFrom": "ofelia@example.com",
    "emailTo": "admin@example.com"
  },
  "jobs": {
    "exec": [...],
    "run": [...],
    "local": [...],
    "service": [...]
  }
}

Update Global Configuration

PATCH /api/config/global
Content-Type: application/json

{
  "dockerPollInterval": 60,
  "slackChannel": "#alerts"
}

WebSocket Events

Subscribe to Real-time Events

const ws = new WebSocket('ws://localhost:8080/api/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data
4C1E
.type, data.payload);
};

Event Types:

  • job.started: Job execution started
  • job.completed: Job execution completed
  • job.failed: Job execution failed
  • job.added: New job added
  • job.updated: Job configuration updated
  • job.removed: Job removed
  • scheduler.started: Scheduler started
  • scheduler.stopped: Scheduler stopped

Error Responses

All endpoints return consistent error responses:

{
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Job 'backup' not found",
    "details": {
      "job": "backup",
      "timestamp": "2024-01-01T12:00:00Z"
    }
  }
}

Error Codes

  • UNAUTHORIZED: Missing or invalid authentication
  • FORBIDDEN: Insufficient permissions
  • JOB_NOT_FOUND: Job does not exist
  • INVALID_SCHEDULE: Invalid cron expression
  • DOCKER_ERROR: Docker API error
  • EXECUTION_ERROR: Job execution failed
  • VALIDATION_ERROR: Invalid input data
  • INTERNAL_ERROR: Server error

Rate Limiting

API requests are rate-limited to prevent abuse:

  • Default limit: 100 requests per minute
  • Burst capacity: 10 requests

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

CORS Configuration

Cross-Origin Resource Sharing (CORS) can be configured:

cors:
  allowed_origins:
    - http://localhost:3000
    - https://app.example.com
  allowed_methods:
    - GET
    - POST
    - PUT
    - DELETE
  allowed_headers:
    - Authorization
    - Content-Type
  max_age: 86400

See also: Web Package | Configuration Guide | Project Index
0