Skip to content

Latest commit

 

History

History
530 lines (425 loc) · 11.5 KB

API_GUIDE.md

File metadata and controls

530 lines (425 loc) · 11.5 KB

API Usage Guide - SIPp Distributed Master

Base URL

http://localhost:8008

Interactive API Documentation

Access the full interactive API documentation at:

http://localhost:8008/docs  (Swagger UI)
http://localhost:8008/redoc (ReDoc)

Scenarios API

1. Create Scenario

Endpoint: POST /api/scenarios

curl -X POST http://localhost:8000/api/scenarios \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic SIP Call",
    "description": "Simple UAC to UAS call",
    "scenario_file": "/sipp/sipp_scenarios/uac.xml",
    "pcap_files": ["g711a.pcap"],
    "default_params": {
      "calls": 10,
      "rate": 1,
      "duration": 300
    }
  }'

Response (201):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Basic SIP Call",
  "description": "Simple UAC to UAS call",
  "scenario_file": "/sipp/sipp_scenarios/uac.xml",
  "pcap_files": ["g711a.pcap"],
  "default_params": {"calls": 10, "rate": 1, "duration": 300},
  "created_at": "2026-02-05T10:30:00",
  "updated_at": "2026-02-05T10:30:00"
}

2. List All Scenarios

Endpoint: GET /api/scenarios

curl http://localhost:8000/api/scenarios

Response (200):

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Basic SIP Call",
    ...
  }
]

3. Get Scenario Details

Endpoint: GET /api/scenarios/{scenario_id}

curl http://localhost:8000/api/scenarios/a1b2c3d4-e5f6-7890-abcd-ef1234567890

4. Update Scenario

Endpoint: PUT /api/scenarios/{scenario_id}

curl -X PUT http://localhost:8000/api/scenarios/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Scenario Name",
    "pcap_files": ["g711a.pcap", "dtmf.pcap"]
  }'

5. Delete Scenario

Endpoint: DELETE /api/scenarios/{scenario_id}

curl -X DELETE http://localhost:8000/api/scenarios/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Executions API

1. Create Execution

Endpoint: POST /api/executions

# Auto-assign worker
curl -X POST http://localhost:8000/api/executions \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "command_args": {
      "s": "192.168.1.1",
      "p": "5060",
      "r": "100"
    },
    "environment_vars": {
      "MYVAR": "value"
    },
    "description": "Load test with 100 calls per second"
  }'

# Assign specific worker
curl -X POST http://localhost:8000/api/executions \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "worker_id": "w1w2w3w4-e5f6-7890-abcd-ef1234567890",
    "command_args": {"s": "192.168.1.1"}
  }'

Response (201):

{
  "id": "e1e2e3e4-e5f6-7890-abcd-ef1234567890",
  "scenario_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "worker_id": "w1w2w3w4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "command_args": {"s": "192.168.1.1", "p": "5060", "r": "100"},
  "environment_vars": {"MYVAR": "value"},
  "stdout": null,
  "stderr": null,
  "return_code": null,
  "calls_generated": 0,
  "calls_completed": 0,
  "success_rate": 0.0,
  "avg_response_time": 0.0,
  "created_at": "2026-02-05T10:35:00",
  "started_at": null,
  "completed_at": null,
  "description": "Load test with 100 calls per second"
}

2. List Executions with Filtering

Endpoint: GET /api/executions

# List all executions
curl http://localhost:8000/api/executions

# Filter by scenario
curl 'http://localhost:8000/api/executions?scenario_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890'

# Filter by worker
curl 'http://localhost:8000/api/executions?worker_id=w1w2w3w4-e5f6-7890-abcd-ef1234567890'

# Filter by status
curl 'http://localhost:8000/api/executions?status=running'

# Filter by scenario and status
curl 'http://localhost:8000/api/executions?scenario_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&status=completed'

Response (200):

[
  {
    "id": "e1e2e3e4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "calls_completed": 98,
    "success_rate": 98.0,
    ...
  }
]

3. Get Execution Details

Endpoint: GET /api/executions/{execution_id}

curl http://localhost:8000/api/executions/e1e2e3e4-e5f6-7890-abcd-ef1234567890

Response (200):

{
  "id": "e1e2e3e4-e5f6-7890-abcd-ef1234567890",
  "scenario_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "worker_id": "w1w2w3w4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "command_args": {...},
  "stdout": "Calls generated: 100\nCalls completed: 98\nSuccess rate: 98%...",
  "stderr": "",
  "return_code": 0,
  "calls_generated": 100,
  "calls_completed": 98,
  "success_rate": 98.0,
  "avg_response_time": 150.5,
  "created_at": "2026-02-05T10:35:00",
  "started_at": "2026-02-05T10:35:05",
  "completed_at": "2026-02-05T10:36:00",
  "description": "Load test with 100 calls per second"
}

4. Update Execution (Worker Updates Results)

Endpoint: PUT /api/executions/{execution_id}

# Update status to running
curl -X PUT http://localhost:8000/api/executions/e1e2e3e4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -d '{"status": "running"}'

# Update with results
curl -X PUT http://localhost:8000/api/executions/e1e2e3e4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "stdout": "Calls generated: 100\nCalls completed: 98\n...",
    "stderr": "",
    "return_code": 0,
    "calls_generated": 100,
    "calls_completed": 98,
    "success_rate": 98.0,
    "avg_response_time": 150.5
  }'

5. Get Execution Logs

Endpoint: GET /api/executions/{execution_id}/logs

curl http://localhost:8000/api/executions/e1e2e3e4-e5f6-7890-abcd-ef1234567890/logs

Response (200):

[
  {
    "id": 1,
    "execution_id": "e1e2e3e4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2026-02-05T10:35:00.000",
    "level": "INFO",
    "source": "master",
    "message": "Execution created for scenario a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  {
    "id": 2,
    "execution_id": "e1e2e3e4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2026-02-05T10:35:00.100",
    "level": "INFO",
    "source": "master",
    "message": "Assigned worker: w1w2w3w4-e5f6-7890-abcd-ef1234567890"
  },
  {
    "id": 3,
    "execution_id": "e1e2e3e4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2026-02-05T10:35:05.000",
    "level": "INFO",
    "source": "worker",
    "message": "Execution started"
  },
  {
    "id": 4,
    "execution_id": "e1e2e3e4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2026-02-05T10:36:00.000",
    "level": "INFO",
    "source": "worker",
    "message": "Execution completed successfully"
  }
]

6. Add Log Entry

Endpoint: POST /api/executions/{execution_id}/logs

curl -X POST 'http://localhost:8000/api/executions/e1e2e3e4-e5f6-7890-abcd-ef1234567890/logs' \
  -H "Content-Type: application/json" \
  -d '{
    "level": "WARNING",
    "source": "worker",
    "message": "Connection timeout after 30 seconds"
  }'

# Or using query parameters
curl -X POST 'http://localhost:8000/api/executions/e1e2e3e4-e5f6-7890-abcd-ef1234567890/logs?level=ERROR&source=sipp&message=Fatal%20error%20in%20scenario'

Workers API

1. Register Worker (Auto-Discovery)

Endpoint: POST /api/workers

curl -X POST http://localhost:8000/api/workers \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "sipp-worker-external-1",
    "ip_address": "192.168.1.100",
    "port": 9000,
    "cpu_count": 4,
    "memory_gb": 16.0
  }'

Response (200):

{
  "id": "w1w2w3w4-e5f6-7890-abcd-ef1234567890",
  "hostname": "sipp-worker-external-1",
  "ip_address": "192.168.1.100",
  "port": 9000,
  "status": "online",
  "cpu_count": 4,
  "memory_gb": 16.0,
  "last_heartbeat": "2026-02-05T10:30:00",
  "is_healthy": true,
  "created_at": "2026-02-05T10:30:00",
  "updated_at": "2026-02-05T10:30:00"
}

2. List All Workers

Endpoint: GET /api/workers

curl http://localhost:8000/api/workers

Response (200):

[
  {
    "id": "w1w2w3w4-e5f6-7890-abcd-ef1234567890",
    "hostname": "sipp-worker-1",
    "status": "online",
    "is_healthy": true,
    ...
  },
  {
    "id": "w5w6w7w8-e5f6-7890-abcd-ef1234567890",
    "hostname": "sipp-worker-2",
    "status": "offline",
    "is_healthy": false,
    ...
  }
]

3. Get Worker Details

Endpoint: GET /api/workers/{worker_id}

curl http://localhost:8000/api/workers/w1w2w3w4-e5f6-7890-abcd-ef1234567890

4. Update Worker Status

Endpoint: PUT /api/workers/{worker_id}

curl -X PUT http://localhost:8000/api/workers/w1w2w3w4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "busy",
    "is_healthy": true
  }'

5. Send Heartbeat

Endpoint: POST /api/workers/{worker_id}/heartbeat

curl -X POST http://localhost:8000/api/workers/w1w2w3w4-e5f6-7890-abcd-ef1234567890/heartbeat

Response (200):

{"message": "Heartbeat received"}

6. Unregister Worker

Endpoint: DELETE /api/workers/{worker_id}

curl -X DELETE http://localhost:8000/api/workers/w1w2w3w4-e5f6-7890-abcd-ef1234567890

Health Check API

System Health

Endpoint: GET /health

curl http://localhost:8000/health

Response (200):

{
  "status": "healthy",
  "service": "sipp-master"
}

Complete End-to-End Example

#!/bin/bash

# 1. Create a scenario
SCENARIO=$(curl -s -X POST http://localhost:8000/api/scenarios \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Scenario",
    "scenario_file": "/sipp/sipp_scenarios/uac.xml",
    "pcap_files": ["g711a.pcap"]
  }')

SCENARIO_ID=$(echo $SCENARIO | jq -r '.id')
echo "Created scenario: $SCENARIO_ID"

# 2. List workers
WORKERS=$(curl -s http://localhost:8000/api/workers)
echo "Available workers:"
echo $WORKERS | jq '.[] | {id, hostname, status}'

# 3. Create execution
EXECUTION=$(curl -s -X POST http://localhost:8000/api/executions \
  -H "Content-Type: application/json" \
  -d "{
    \"scenario_id\": \"$SCENARIO_ID\",
    \"command_args\": {
      \"s\": \"192.168.1.1\",
      \"r\": \"100\"
    },
    \"description\": \"Load test\"
  }")

EXECUTION_ID=$(echo $EXECUTION | jq -r '.id')
echo "Created execution: $EXECUTION_ID"

# 4. Poll for completion
for i in {1..60}; do
  STATUS=$(curl -s http://localhost:8000/api/executions/$EXECUTION_ID | jq -r '.status')
  echo "Status: $STATUS"
  
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi
  
  sleep 1
done

# 5. Get final results
RESULTS=$(curl -s http://localhost:8000/api/executions/$EXECUTION_ID)
echo "Final Results:"
echo $RESULTS | jq '{status, calls_completed, success_rate, avg_response_time}'

# 6. Get logs
LOGS=$(curl -s http://localhost:8000/api/executions/$EXECUTION_ID/logs)
echo "Execution Logs:"
echo $LOGS | jq '.[] | {timestamp, level, source, message}'

Error Responses

404 - Not Found

{"detail": "Execution not found"}

409 - Conflict

{"detail": "Worker already registered"}

500 - Server Error

{"detail": "Failed to create execution: database error"}

Rate Limiting & Pagination

Currently, the API has no built-in rate limiting or pagination. For production use, consider adding:

  • Rate limiting: 100 requests per minute per IP
  • Pagination: Limit list endpoints to 100 items per page
  • Filtering: More granular filtering options

See IMPLEMENTATION_SUMMARY.md for production readiness notes.