<--inspect --trace-warnings --signal Prism.js CSS -->
ScoutQuest / Documentation / REST API Reference

REST API Reference

Complete REST API documentation for ScoutQuest service discovery server.

API Version: 1.0 Base URL: http://localhost:8080/api

Authentication

ScoutQuest supports multiple authentication methods:

API Key Authentication

# Include API key in header
curl -H "X-API-Key: your-api-key-here" \
  http://localhost:8080/api/services

JWT Token Authentication

# Include JWT token in Authorization header
curl -H "Authorization: Bearer your-jwt-token-here" \
  http://localhost:8080/api/services

No Authentication (Development)

For development environments, authentication can be disabled in the configuration.

Service Management

POST /api/services Register a new service instance

Request Body

{
  "name": "user-service",
  "host": "localhost",
  "port": 3000,
  "metadata": {
    "version": "1.2.3",
    "environment": "production",
    "region": "us-east-1",
    "team": "backend",
    "capabilities": ["users", "auth"]
  },
  "tags": ["api", "v1", "production"],
  "healthCheckUrl": "http://localhost:3000/health"
}

Response (201 Created)

{
  "id": "user-service-1a2b3c4d",
  "name": "user-service",
  "host": "localhost",
  "port": 3000,
  "status": "healthy",
  "metadata": {
    "version": "1.2.3",
    "environment": "production",
    "region": "us-east-1",
    "team": "backend",
    "capabilities": ["users", "auth"]
  },
  "tags": ["api", "v1", "production"],
  "healthCheckUrl": "http://localhost:3000/health",
  "registeredAt": "2024-01-15T10:30:00Z",
  "lastSeen": "2024-01-15T10:30:00Z"
}

cURL Example

curl -X POST http://localhost:8080/api/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-service",
    "host": "localhost",
    "port": 3000,
    "metadata": {
      "version": "1.2.3",
      "environment": "production"
    }
  }'
GET /api/services List all registered services

Query Parameters

  • status - Filter by status: healthy, unhealthy, all (default: healthy)
  • tags - Filter by tags (comma-separated): ?tags=api,v1
  • environment - Filter by environment metadata
  • limit - Limit number of results (default: 100)
  • offset - Pagination offset (default: 0)

Response (200 OK)

{
  "services": [
    {
      "name": "user-service",
      "instanceCount": 3,
      "healthyInstances": 3,
      "unhealthyInstances": 0,
      "tags": ["api", "v1", "production"],
      "lastUpdated": "2024-01-15T10:30:00Z"
    },
    {
      "name": "order-service",
      "instanceCount": 2,
      "healthyInstances": 2,
      "unhealthyInstances": 0,
      "tags": ["api", "v2", "production"],
      "lastUpdated": "2024-01-15T10:25:00Z"
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0
}

cURL Example

# List all services
curl http://localhost:8080/api/services

# Filter by tags
curl http://localhost:8080/api/services?tags=api,production

# Filter by status
curl http://localhost:8080/api/services?status=all
GET /api/services/{service_name} Get a specific service (returns one healthy instance)

Path Parameters

  • service_name - Name of the service to discover

Query Parameters

  • tags - Filter by tags
  • strategy - Load balancing strategy: round_robin, random (default: round_robin)
  • prefer_local - Prefer local instances: true, false

Response (200 OK)

{
  "id": "user-service-1a2b3c4d",
  "name": "user-service",
  "host": "localhost",
  "port": 3000,
  "status": "healthy",
  "metadata": {
    "version": "1.2.3",
    "environment": "production",
    "region": "us-east-1"
  },
  "tags": ["api", "v1", "production"],
  "healthCheckUrl": "http://localhost:3000/health",
  "registeredAt": "2024-01-15T10:30:00Z",
  "lastSeen": "2024-01-15T10:35:00Z",
  "healthStatus": {
    "status": "healthy",
    "lastCheck": "2024-01-15T10:35:00Z",
    "responseTime": 15,
    "checks": {
      "database": "healthy",
      "redis": "healthy"
    }
  }
}

Error Responses

# 404 Not Found - Service not registered
{
  "error": "service_not_found",
  "message": "Service 'unknown-service' not found",
  "timestamp": "2024-01-15T10:30:00Z"
}

# 503 Service Unavailable - No healthy instances
{
  "error": "service_unavailable",
  "message": "Service 'user-service' has no healthy instances",
  "timestamp": "2024-01-15T10:30:00Z"
}

cURL Example

# Discover service
curl http://localhost:8080/api/services/user-service

# With filtering
curl "http://localhost:8080/api/services/user-service?tags=production&strategy=random"
GET /api/services/{service_name}/instances List all instances of a service

Response (200 OK)

{
  "serviceName": "user-service",
  "instances": [
    {
      "id": "user-service-1a2b3c4d",
      "host": "localhost",
      "port": 3000,
      "status": "healthy",
      "metadata": {
        "version": "1.2.3",
        "load": 0.65
      },
      "registeredAt": "2024-01-15T10:30:00Z",
      "lastSeen": "2024-01-15T10:35:00Z"
    },
    {
      "id": "user-service-5e6f7g8h",
      "host": "localhost",
      "port": 3001,
      "status": "healthy",
      "metadata": {
        "version": "1.2.3",
        "load": 0.45
      },
      "registeredAt": "2024-01-15T10:31:00Z",
      "lastSeen": "2024-01-15T10:35:00Z"
    }
  ],
  "total": 2,
  "healthyCount": 2,
  "unhealthyCount": 0
}
DELETE /api/services/{instance_id} Deregister a service instance

Response (204 No Content)

Empty response body on successful deregistration.

cURL Example

curl -X DELETE http://localhost:8080/api/services/user-service-1a2b3c4d
PUT /api/services/{instance_id}/heartbeat Send heartbeat to keep instance alive

Request Body (Optional)

{
  "metadata": {
    "load": 0.75,
    "connections": 150,
    "version": "1.2.4"
  }
}

Response (200 OK)

{
  "message": "Heartbeat received",
  "instanceId": "user-service-1a2b3c4d",
  "lastSeen": "2024-01-15T10:35:00Z"
}

Health Check Endpoints

GET /health ScoutQuest server health check

Response (200 OK)

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:35:00Z",
  "version": "1.0.0",
  "uptime": 3600,
  "checks": {
    "database": {
      "status": "healthy",
      "responseTime": 5
    },
    "redis": {
      "status": "healthy",
      "responseTime": 2
    }
  },
  "stats": {
    "totalServices": 15,
    "totalInstances": 47,
    "healthyInstances": 45,
    "unhealthyInstances": 2
  }
}
GET /ready ScoutQuest server readiness check

Response (200 OK)

{
  "status": "ready",
  "timestamp": "2024-01-15T10:35:00Z"
}
GET /api/services/{service_name}/health Get health status of all service instances

Response (200 OK)

{
  "serviceName": "user-service",
  "overallStatus": "healthy",
  "instances": [
    {
      "id": "user-service-1a2b3c4d",
      "host": "localhost",
      "port": 3000,
      "status": "healthy",
      "lastCheck": "2024-01-15T10:35:00Z",
      "responseTime": 15,
      "checks": {
        "database": "healthy",
        "redis": "healthy"
      }
    }
  ]
}

Metrics & Monitoring

GET /metrics Prometheus-format metrics

Response (200 OK)

# HELP scoutquest_services_total Total number of registered services
# TYPE scoutquest_services_total gauge
scoutquest_services_total 15

# HELP scoutquest_instances_total Total number of service instances
# TYPE scoutquest_instances_total gauge
scoutquest_instances_total{status="healthy"} 45
scoutquest_instances_total{status="unhealthy"} 2

# HELP scoutquest_http_requests_total Total number of HTTP requests
# TYPE scoutquest_http_requests_total counter
scoutquest_http_requests_total{method="GET",endpoint="/api/services",status="200"} 1234
scoutquest_http_requests_total{method="POST",endpoint="/api/services",status="201"} 89

# HELP scoutquest_http_request_duration_seconds HTTP request duration
# TYPE scoutquest_http_request_duration_seconds histogram
scoutquest_http_request_duration_seconds_bucket{method="GET",endpoint="/api/services",le="0.005"} 450
scoutquest_http_request_duration_seconds_bucket{method="GET",endpoint="/api/services",le="0.01"} 890
GET /api/stats Get system statistics

Response (200 OK)

{
  "timestamp": "2024-01-15T10:35:00Z",
  "uptime": 3600,
  "services": {
    "total": 15,
    "byStatus": {
      "healthy": 13,
      "unhealthy": 2
    },
    "byEnvironment": {
      "production": 10,
      "staging": 3,
      "development": 2
    }
  },
  "instances": {
    "total": 47,
    "healthy": 45,
    "unhealthy": 2,
    "averageResponseTime": 25
  },
  "requests": {
    "total": 12345,
    "last24h": 2890,
    "successRate": 99.5
  },
  "memory": {
    "used": 134217728,
    "total": 536870912,
    "percentage": 25.0
  }
}

Proxy Endpoints

ScoutQuest can proxy HTTP requests to discovered services.

GET /api/proxy/{service_name}/** Proxy GET request to service

cURL Example

# Proxies to a healthy instance of user-service
curl http://localhost:8080/api/proxy/user-service/api/users/123
POST /api/proxy/{service_name}/** Proxy POST request to service

cURL Example

curl -X POST http://localhost:8080/api/proxy/user-service/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "john@example.com"}'

WebSocket Events

ScoutQuest provides real-time updates via WebSocket connections.

WS /api/events WebSocket connection for real-time events

Event Types

# Service registered
{
  "type": "service_registered",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "instanceId": "user-service-1a2b3c4d",
    "serviceName": "user-service",
    "host": "localhost",
    "port": 3000
  }
}

# Service deregistered
{
  "type": "service_deregistered",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "instanceId": "user-service-1a2b3c4d",
    "serviceName": "user-service"
  }
}

# Health status changed
{
  "type": "health_status_changed",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "instanceId": "user-service-1a2b3c4d",
    "serviceName": "user-service",
    "previousStatus": "healthy",
    "currentStatus": "unhealthy"
  }
}

Error Responses

All API endpoints return structured error responses:

HTTP Status Codes

400 Bad Request

Invalid request data or parameters

401 Unauthorized

Missing or invalid authentication credentials

403 Forbidden

Insufficient permissions for the requested operation

404 Not Found

Requested service or resource not found

409 Conflict

Service instance already registered

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Internal server error

503 Service Unavailable

Service has no healthy instances or server is overloaded

Error Response Format

{
  "error": "service_not_found",
  "message": "Service 'unknown-service' not found",
  "timestamp": "2024-01-15T10:35:00Z",
  "requestId": "req-1a2b3c4d5e6f",
  "details": {
    "serviceName": "unknown-service",
    "availableServices": ["user-service", "order-service"]
  }
}

Common Error Codes

  • service_not_found - Requested service is not registered
  • service_unavailable - Service has no healthy instances
  • invalid_request - Request body or parameters are invalid
  • authentication_failed - Invalid API key or JWT token
  • rate_limit_exceeded - Too many requests from client
  • internal_error - Unexpected server error

Rate Limiting

ScoutQuest implements rate limiting to prevent abuse:

# Rate limit headers in responses
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000
X-RateLimit-Window: 60

Default Limits:

  • 1000 requests per minute per API key
  • 100 concurrent connections per IP
  • 10 service registrations per minute per service name

API Versioning

ScoutQuest uses URL-based versioning:

# Current version (v1)
http://localhost:8080/api/services

# Explicit version
http://localhost:8080/api/v1/services

# Future versions
http://localhost:8080/api/v2/services

Version compatibility:

  • v1 - Current stable version
  • Backward compatibility guaranteed within major versions
  • Deprecation notices provided 6 months before removal

SDKs and Tools

While you can use the REST API directly, we recommend using our official SDKs:

JavaScript/TypeScript SDK

Full-featured client with advanced features

Rust SDK

High-performance client with async support

CLI Tools

Command-line tools for testing and administration
<--inspect --trace-warnings --signal Prism.js JavaScript -->