This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

REST API

    REST API reference for Piglet Run.

    Overview

    Piglet Run provides a REST API for programmatic access to all features.

    Base URL

    http://<ip>/api/v1

    Authentication

    API Key

    curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost/api/v1/status

    Generate API Key

    pig api key create --name mykey

    Endpoints

    System

    Get Status

    GET /api/v1/status

    Response:

    {
  "status": "healthy",
  "version": "2.5.0",
  "uptime": 86400,
  "services": {
    "postgres": "running",
    "vscode": "running",
    "jupyter": "running"
  }
}

    Get System Info

    GET /api/v1/system

    Response:

    {
  "hostname": "piglet",
  "os": "Ubuntu 22.04",
  "cpu": 4,
  "memory": "8GB",
  "disk": "100GB"
}

    Databases

    List Databases

    GET /api/v1/databases

    Response:

    {
  "databases": [
    {
      "name": "postgres",
      "owner": "dba",
      "size": "50MB"
    }
  ]
}

    Create Database

    POST /api/v1/databases
Content-Type: application/json

{
  "name": "mydb",
  "owner": "dba"
}

    Delete Database

    DELETE /api/v1/databases/{name}

    Backups

    List Backups

    GET /api/v1/backups

    Response:

    {
  "backups": [
    {
      "id": "backup-20240115",
      "type": "full",
      "size": "1.2GB",
      "created_at": "2024-01-15T02:00:00Z"
    }
  ]
}

    Create Backup

    POST /api/v1/backups
Content-Type: application/json

{
  "type": "full",
  "databases": ["postgres"]
}

    Restore Backup

    POST /api/v1/backups/{id}/restore
Content-Type: application/json

{
  "target_time": "2024-01-15T14:30:00Z"
}

    Services

    List Services

    GET /api/v1/services

    Response:

    {
  "services": [
    {
      "name": "postgres",
      "status": "running",
      "port": 5432
    },
    {
      "name": "vscode",
      "status": "running",
      "port": 8080
    }
  ]
}

    Control Service

    POST /api/v1/services/{name}/{action}

    Actions: start, stop, restart

    Snapshots

    List Snapshots

    GET /api/v1/snapshots

    Create Snapshot

    POST /api/v1/snapshots
Content-Type: application/json

{
  "name": "snap-20240115",
  "description": "Before upgrade"
}

    Restore Snapshot

    POST /api/v1/snapshots/{name}/restore

    Users

    List Users

    GET /api/v1/users

    Create User

    POST /api/v1/users
Content-Type: application/json

{
  "username": "newuser",
  "password": "secure_password",
  "databases": ["mydb"]
}

    Error Responses

    {
  "error": {
    "code": "NOT_FOUND",
    "message": "Database not found",
    "details": {
      "database": "nonexistent"
    }
  }
}

    Error Codes

    CodeHTTP StatusDescription
    UNAUTHORIZED401Invalid or missing API key
    FORBIDDEN403Insufficient permissions
    NOT_FOUND404Resource not found
    CONFLICT409Resource already exists
    INTERNAL_ERROR500Server error

    Rate Limiting

    • Default: 100 requests per minute
    • Burst: 20 requests

    Headers:

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

    SDK Examples

    Python

    import requests

api_key = "YOUR_API_KEY"
base_url = "http://localhost/api/v1"

headers = {"Authorization": f"Bearer {api_key}"}

# Get status
response = requests.get(f"{base_url}/status", headers=headers)
print(response.json())

# Create database
response = requests.post(
    f"{base_url}/databases",
    headers=headers,
    json={"name": "mydb", "owner": "dba"}
)

    JavaScript

    const apiKey = "YOUR_API_KEY";
const baseUrl = "http://localhost/api/v1";

// Get status
fetch(`${baseUrl}/status`, {
  headers: { Authorization: `Bearer ${apiKey}` }
})
  .then(res => res.json())
  .then(data => console.log(data));

    See Also