Skip to content

API.md

Latest commit

 

History

History
419 lines (347 loc) · 7.78 KB

API.md

File metadata and controls

419 lines (347 loc) · 7.78 KB
Raw

PyJob REST API Documentation

Authentication

PyJob supports three authentication methods:

1. JWT Bearer Token

Authorization: Bearer <jwt_token>

2. API Key

X-API-Key: <api_key>

3. Basic Authentication

Authorization: Basic <base64_encoded_credentials>

Authentication Endpoints

Register User

POST /api/auth/register
Content-Type: application/json

{
  "username": "myuser",
  "email": "user@example.com",
  "password": "securepassword",
  "role": "user"
}

Login

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

{
  "username": "myuser",
  "password": "securepassword"
}

Get Token (using Basic Auth)

POST /api/auth/token
Authorization: Basic <base64_encoded_credentials>

Get Current User Info

GET /api/auth/me
Authorization: Bearer <jwt_token>

Generate API Key

POST /api/auth/api-keys
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "My API Key",
  "description": "API key for mobile app integration"
}

List API Keys

GET /api/auth/api-keys
Authorization: Bearer <jwt_token>

Revoke API Key

DELETE /api/auth/api-keys/:name
Authorization: Bearer <jwt_token>

JWT Token Management

Generate JWT Token

POST /api/auth/tokens
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "description": "API integration token for mobile app"
}

List JWT Tokens

GET /api/auth/tokens
Authorization: Bearer <jwt_token>

Get Specific Token Info

GET /api/auth/tokens/:tokenId
Authorization: Bearer <jwt_token>

Update Token Description

PUT /api/auth/tokens/:tokenId/description
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "description": "Updated description"
}

Extend Token Expiration

POST /api/auth/tokens/:tokenId/extend
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "additionalHours": 48
}

Revoke JWT Token

DELETE /api/auth/tokens/:tokenId
Authorization: Bearer <jwt_token>

Clean Up Expired Tokens

POST /api/auth/tokens/cleanup
Authorization: Bearer <jwt_token>

Job Management Endpoints

List Jobs

GET /api/jobs?page=1&limit=10&active=true
  • Authentication: Optional (filtered data for non-authenticated users)
  • Query Parameters:
    • page: Page number (default: 1)
    • limit: Items per page (default: 10)
    • active: Filter by active status (true/false)

Get Job by ID

GET /api/jobs/:id
  • Authentication: Optional (filtered data for non-authenticated users)

Get Complete Job Details

GET /api/jobs/:id/details
  • Authentication: Required
  • Description: Returns complete job details including sensitive information (Python script, requirements, environment variables)

Get Job Python Script

GET /api/jobs/:id/script
  • Authentication: Required
  • Description: Returns only the Python script content

Get Job Requirements

GET /api/jobs/:id/requirements
  • Authentication: Required
  • Description: Returns only the Python package requirements

Get Job Environment Variables

GET /api/jobs/:id/env
  • Authentication: Required
  • Description: Returns only the environment variables

Create Job

POST /api/jobs
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "my-python-job",
  "description": "A sample Python job",
  "cronPattern": "0 */6 * * *",
  "pythonScript": "print('Hello from Python!')",
  "requirements": ["requests", "numpy"],
  "environmentVariables": {
    "API_KEY": "your-api-key",
    "DEBUG": "true"
  },
  "isActive": true,
  "timeout": 300000,
  "maxRetries": 3
}

Update Job

PUT /api/jobs/:id
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "updated-job-name",
  "description": "Updated description",
  "cronPattern": "0 */12 * * *"
}

Delete Job

DELETE /api/jobs/:id
Authorization: Bearer <jwt_token>

Execute Job Manually

POST /api/jobs/:id/execute
Authorization: Bearer <jwt_token>

Toggle Job Status

PATCH /api/jobs/:id/toggle
Authorization: Bearer <jwt_token>

Get Job Executions

GET /api/jobs/:id/executions?page=1&limit=10&status=completed
Authorization: Bearer <jwt_token>

Get Job Logs

GET /api/jobs/:id/logs?page=1&limit=20&status=failed
Authorization: Bearer <jwt_token>

System Endpoints

Get Job Statistics

GET /api/jobs/stats/overview
  • Authentication: Optional

Search Jobs

GET /api/jobs/search?q=python&page=1&limit=10
  • Authentication: Optional

Get Scheduled Jobs Status

GET /api/jobs/scheduled/status
Authorization: Bearer <jwt_token>

Get System Health

GET /api/jobs/health/status
  • Authentication: Optional

Export Jobs Data (Admin Only)

GET /api/jobs/export?format=json
Authorization: Bearer <jwt_token>

System Health Check

GET /health

Job Schema

{
  "name": "string (required, unique, 1-100 chars)",
  "description": "string (optional, max 500 chars)",
  "cronPattern": "string (required, valid CRON pattern)",
  "pythonScript": "string (required, Python code)",
  "requirements": ["array of strings (Python packages)"],
  "environmentVariables": {
    "key": "value (string)"
  },
  "isActive": "boolean (default: true)",
  "timeout": "number (milliseconds, 1000-3600000, default: 300000)",
  "maxRetries": "number (0-10, default: 3)"
}

CRON Pattern Format

Standard 5-field CRON pattern:

* * * * *
│ │ │ │ │
│ │ │ │ └─── Day of week (0-6)
│ │ │ └───── Month (1-12)
│ │ └─────── Day of month (1-31)
│ └───────── Hour (0-23)
└─────────── Minute (0-59)

Examples:

  • 0 */6 * * * - Every 6 hours
  • 0 9 * * 1-5 - Every weekday at 9 AM
  • */15 * * * * - Every 15 minutes

Response Formats

Success Response

{
  "message": "Operation successful",
  "data": { ... }
}

Error Response

{
  "error": "Error message",
  "details": { ... }
}

Paginated Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "pages": 10
  }
}

Rate Limiting

  • General API: 100 requests per 15 minutes per IP
  • Authentication: 5 requests per 15 minutes per IP

Examples

Complete Workflow

  1. Register a user:
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","email":"admin@example.com","password":"securepass","role":"admin"}'
  1. Login and get token:
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"securepass"}'
  1. Create a job:
curl -X POST http://localhost:3000/api/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "data-fetcher",
    "description": "Fetch data every hour",
    "cronPattern": "0 * * * *",
    "pythonScript": "import requests\nprint(\"Fetching data...\")",
    "requirements": ["requests"]
  }'
  1. Execute job manually:
curl -X POST http://localhost:3000/api/jobs/{job-id}/execute \
  -H "Authorization: Bearer <token>"
  1. Check job status:
curl http://localhost:3000/api/jobs/stats/overview \
  -H "Authorization: Bearer <token>"

Using API Key

curl http://localhost:3000/api/jobs \
  -H "X-API-Key: pyjob_your_api_key_here"

Using Basic Auth

curl http://localhost:3000/api/jobs \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"