WAIIDE API Reference

Calliope Integration: This component is integrated into the Calliope AI platform. Some features and configurations may differ from the upstream project.

Overview

WAIIDE provides JupyterHub-compatible API endpoints for health checking, service discovery, and status monitoring. The API is available in both JupyterHub and standalone modes.

Base URL

The base URL depends on your deployment mode:

• JupyterHub Mode: https://hub.example.com/user/{username}/
• Standalone Mode: http://localhost:8070/

Authentication

• JupyterHub Mode: Authentication handled by JupyterHub OAuth
• Standalone Mode: No authentication (for development use)

API Endpoints

GET /api

Returns comprehensive service information and status.

Response:

{
  "status": "running",
  "user": "username",
  "server": "waiide",
  "version": "1.0.0",
  "mode": "jupyterhub",
  "service_prefix": "/user/username/",
  "services": {
    "WAIIDE": {
      "port": 8071,
      "status": "running",
      "description": "WAIIDE Server (core IDE)"
    },
    "jupyterhub": {
      "port": 8070,
      "status": "running",
      "description": "JupyterHub singleuser with proxy",
      "proxy_path": "/user/username/"
    }
  },
  "endpoints": {
    "api": "/user/username/api",
    "services": "/user/username/api/services"
  }
}

Status Codes:

• 200 OK - Service is running normally

GET /api/services

Returns detailed information about all running services.

Response:

{
  "services": {
    "WAIIDE": {
      "name": "WAIIDE Server",
      "port": 8071,
      "status": "running",
      "url": "http://127.0.0.1:8071",
      "proxy_url": "/user/username/ide/",
      "description": "Core IDE functionality"
    },
    "api": {
      "name": "WAIIDE API Server",
      "port": 8070,
      "status": "running",
      "url": "http://0.0.0.0:8070/api",
      "proxy_url": "/user/username/api",
      "description": "Custom API endpoints and WAIIDE proxy"
    }
  },
  "total_services": 2,
  "architecture": "jupyterhub-integrated"
}

Service Status Values:

• running - Service is operational
• stopped - Service is not responding

GET /api/status

Basic health check endpoint for JupyterHub compatibility.

Response:

{
  "status": "running",
  "user": "username",
  "server": "waiide",
  "version": "1.0.0",
  "service_prefix": "/user/username/",
  "note": "Health checking handled by JupyterHub"
}

GET /api/*

Catch-all for other API paths, returns basic status for JupyterHub compatibility.

Response: Same as /api/status

WAIIDE Server Access

All non-API paths are proxied to the WAIIDE Server:

GET|POST|PUT|DELETE|OPTIONS /*

Any request not matching /api/* is proxied to WAIIDE Server with:

1. URL Path Stripping: JupyterHub prefix removed
2. Header Forwarding: All headers except problematic ones
3. Response Rewriting: URLs in HTML/CSS/JS updated with prefix
4. WebSocket Support: Upgrade requests properly handled

Example:

• Request: /user/username/workspace/file.txt
• Proxied to WAIIDE as: /workspace/file.txt

WebSocket Support

WebSocket connections are fully supported for WAIIDE features:

WebSocket Upgrade

Request Headers Required:

Upgrade: websocket
Connection: Upgrade

Supported Paths:

• Any WAIIDE WebSocket endpoint
• Automatic path stripping applied
• Bidirectional data forwarding

URL Rewriting

The API server automatically rewrites URLs in responses when running with a JupyterHub prefix.

Rewritten Content Types

• HTML (text/html)
• JavaScript (application/javascript, text/javascript)
• CSS (text/css)
• JSON (application/json)

Rewrite Patterns

• HTML attributes: src, href, action
• JavaScript: fetch(), XMLHttpRequest
• WebSocket: new WebSocket()
• CSS: url()
• Import statements

Example:

<!-- Original -->
<script src="/static/app.js"></script>

<!-- Rewritten -->
<script src="/user/username/static/app.js"></script>

Error Responses

404 Not Found

Resource not found on WAIIDE Server.

502 Bad Gateway

WAIIDE Server is not responding.

{
  "error": "Bad Gateway - WAIIDE Server not available"
}

500 Internal Server Error

Unexpected error in API server.

{
  "error": "Internal Server Error"
}

Response Headers

All API responses include:

Content-Type: application/json
Access-Control-Allow-Origin: *

Environment Variables

The API server reads these environment variables:

• PORT - Main service port (default: 8070)
• HOST - Bind address (default: 0.0.0.0)
• JUPYTERHUB_SERVICE_PREFIX - URL prefix for JupyterHub
• JUPYTERHUB_USER - Username from JupyterHub
• LOG_LEVEL - Logging level (default: INFO)

Health Checking

For monitoring and orchestration:

1. Liveness Check: GET /api/status

   • Returns 200 if API server is responsive

2. Readiness Check: GET /api/services

   • Returns 200 if all services are running
   • Check services.WAIIDE.status === "running"

Usage Examples

Check Service Status

curl http://localhost:8070/api

Monitor WAIIDE Health

curl http://localhost:8070/api/services | jq '.services.WAIIDE.status'

Access WAIIDE

# Browser
open http://localhost:8070/ide/

# With JupyterHub prefix
open https://hub.example.com/user/username/

Implementation Notes

1. Content Buffering: Responses are buffered for rewriting
2. Timeout: 30-second timeout for WAIIDE requests
3. Logging: All requests logged with path transformation
4. Error Handling: Graceful degradation on WAIIDE failure