Phase 2: API Interface

5.1 Introduction to Surgical Robot APIs

Phase 2 of WIA-ROB-006 defines standardized Application Programming Interfaces (APIs) enabling programmatic control, monitoring, and integration of surgical robots. RESTful APIs, WebSocket connections, and standardized protocols create an open ecosystem where third-party developers can build compatible applications, research tools, training simulators, and OR integration systems.

5.2 REST API Architecture

Core API Endpoints

Endpoint	Method	Purpose	Authentication
/api/v1/robot/status	GET	Retrieve robot system status	OAuth 2.0
/api/v1/robot/control	POST	Send control commands	OAuth 2.0 + Role
/api/v1/instruments	GET	List installed instruments	OAuth 2.0
/api/v1/instruments/{id}/move	POST	Command instrument movement	OAuth 2.0 + Role
/api/v1/video/stream	WebSocket	Real-time video streaming	OAuth 2.0
/api/v1/telemetry	WebSocket	Real-time telemetry stream	OAuth 2.0
/api/v1/procedures	GET/POST	Procedure management	OAuth 2.0
/api/v1/emergency/stop	POST	Emergency stop activation	None (safety critical)

API Request Example

POST /api/v1/instruments/ARM-1/move
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "target_position": {
    "x": 125.5,
    "y": 68.3,
    "z": -24.1
  },
  "target_orientation": {
    "roll": 15.0,
    "pitch": -9.0,
    "yaw": 46.0
  },
  "velocity": 10.0,
  "acceleration": 5.0,
  "collision_avoidance": true
}

5.3 Real-Time Video Streaming

WebRTC Protocol

WIA-ROB-006 specifies WebRTC (Web Real-Time Communication) for low-latency video streaming:

Codec: VP9 or H.265 with hardware acceleration
Resolution: Adaptive 720p-4K based on bandwidth
Latency: End-to-end < 100ms for real-time control
Bandwidth: 5-50 Mbps depending on quality
Encryption: DTLS-SRTP mandatory for all streams

Multi-Stream Support

Stream Type	Resolution	FPS	Use Case
Primary Surgical View	4K (3840x2160)	60	Main display at console
Secondary View	1080p	30	Assistant surgeon display
Teaching Stream	1080p	30	Observation room broadcast
Recording Stream	4K	60	Archival and review
Thumbnail Preview	480p	15	OR monitoring dashboard

5.4 Haptic Feedback Interfaces

Force Feedback API

Standardized haptic feedback API enables force-reflecting master manipulators:

WebSocket: ws://robot.example.com/api/v1/haptic

// Incoming force data from robot (100-1000 Hz)
{
  "timestamp": "2025-01-15T14:23:45.123Z",
  "instrument_id": "ARM-1",
  "force_vector": {"x": 0.23, "y": -0.15, "z": 0.87},
  "contact_state": "soft_tissue",
  "vibration": {"frequency": 120, "amplitude": 0.05}
}

// Outgoing haptic rendering command
{
  "master_id": "CONSOLE-RIGHT",
  "force_feedback": {"x": 0.23, "y": -0.15, "z": 0.87},
  "scaling_factor": 1.5,
  "damping": 0.1
}

5.5 Instrument Control APIs

Movement Control

Position Control: Target absolute position in 3D space
Velocity Control: Continuous motion at specified velocity
Force Control: Apply specified force to tissues
Hybrid Control: Combination of position and force control

Safety Constraints

Constraint	Limit	Enforcement
Maximum Velocity	100 mm/s	Hardware + software limiting
Maximum Force	10 N	Torque limiting + monitoring
Workspace Boundaries	Configurable 3D volume	Collision detection + prevention
Joint Limits	Per-joint angle limits	Encoder monitoring
Collision Avoidance	50mm minimum separation	Real-time proximity detection

5.6 Authentication and Security

OAuth 2.0 Implementation

All API access requires OAuth 2.0 authentication with role-based access control:

Surgeon Role: Full control authority, all APIs accessible
Assistant Role: Camera control, limited instrument access
Observer Role: Read-only access, video streams, telemetry
Technician Role: System diagnostics, maintenance, calibration
Administrator Role: System configuration, user management

TLS 1.3 Encryption

All HTTP/HTTPS traffic encrypted with TLS 1.3
Perfect forward secrecy (PFS) required
Certificate pinning for robot-to-console connections
Mutual authentication (client and server certificates)

5.7 WebSocket for Low-Latency Communication

Telemetry Streaming

WebSocket: wss://robot.example.com/api/v1/telemetry

// Real-time data stream (30-60 Hz)
{
  "timestamp": "2025-01-15T14:23:45.123Z",
  "instruments": [
    {
      "id": "ARM-1",
      "position": {"x": 123.45, "y": 67.89, "z": -23.45},
      "velocity": {"x": 5.2, "y": -2.1, "z": 1.3},
      "force": {"x": 0.23, "y": -0.15, "z": 0.87}
    }
  ],
  "camera": {
    "zoom": 1.5,
    "focus": 150.0,
    "exposure": "auto"
  }
}

5.8 Error Handling and Recovery

HTTP Status Codes

Code	Meaning	Response Action
200	Success	Continue operation
400	Invalid request	Correct request format
401	Unauthorized	Re-authenticate
403	Forbidden	Insufficient privileges
409	Conflict	Resolve state conflict
500	Server error	Retry with backoff
503	Service unavailable	System maintenance mode

5.9 Batch Operations and Transaction APIs

Batch Command Execution

Complex surgical maneuvers require coordinated multi-instrument movements. Batch APIs enable atomic execution of multiple commands with rollback on failure:

POST /api/v1/batch
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "transactionId": "txn-2025-01-15-001",
  "atomicity": "all_or_nothing",
  "timeout": 5000,
  "commands": [
    {
      "commandId": "cmd-1",
      "endpoint": "/api/v1/instruments/ARM-1/move",
      "payload": {
        "target_position": {"x": 125.5, "y": 68.3, "z": -24.1},
        "velocity": 10.0
      }
    },
    {
      "commandId": "cmd-2",
      "endpoint": "/api/v1/instruments/ARM-2/move",
      "payload": {
        "target_position": {"x": 135.2, "y": 72.1, "z": -22.8},
        "velocity": 10.0
      }
    },
    {
      "commandId": "cmd-3",
      "endpoint": "/api/v1/camera/zoom",
      "payload": {
        "zoom_level": 2.5,
        "focus_point": {"x": 130.0, "y": 70.0, "z": -23.5}
      }
    }
  ]
}

Response:
{
  "transactionId": "txn-2025-01-15-001",
  "status": "success",
  "executionTime": 234,
  "results": [
    {"commandId": "cmd-1", "status": "completed", "latency": 87},
    {"commandId": "cmd-2", "status": "completed", "latency": 91},
    {"commandId": "cmd-3", "status": "completed", "latency": 56}
  ]
}

5.10 SDK Examples and Integration Patterns

Python SDK - Instrument Control

from wia_surgical_robot import SurgicalRobotAPI, InstrumentController

# Initialize API client with OAuth 2.0
api = SurgicalRobotAPI(
    base_url="https://robot.hospital.org/api/v1",
    client_id="surgical-app-001",
    client_secret="secret-key",
    scopes=["robot:read", "robot:control"]
)

# Authenticate
api.authenticate()

# Get instrument controller
arm1 = InstrumentController(api, instrument_id="ARM-1")

# Move to target position
arm1.move_to(
    position=(125.5, 68.3, -24.1),
    orientation=(15.0, -9.0, 46.0),
    velocity=10.0,
    collision_avoidance=True
)

# Monitor movement progress
while not arm1.is_at_target():
    status = arm1.get_status()
    print(f"Progress: {status.progress_percent}% - Distance: {status.distance_to_target}mm")
    time.sleep(0.1)

print("Movement complete")

JavaScript/TypeScript SDK - Real-Time Telemetry

import { SurgicalRobotClient, TelemetryStream } from '@wia/surgical-robot-sdk';

// Initialize client
const client = new SurgicalRobotClient({
  baseUrl: 'https://robot.hospital.org/api/v1',
  apiKey: process.env.ROBOT_API_KEY
});

// Subscribe to real-time telemetry
const stream = new TelemetryStream(client, {
  robotId: 'davinci-si-001',
  streams: ['pose', 'force', 'video'],
  sampleRate: 100 // Hz
});

stream.on('pose', (data) => {
  console.log(`Position: (${data.position.x}, ${data.position.y}, ${data.position.z})`);
  updateVisualization(data);
});

stream.on('force', (data) => {
  if (data.magnitude > 5.0) {
    console.warn(`High force detected: ${data.magnitude}N`);
  }
});

stream.connect();

5.11 API Versioning and Deprecation Policy

WIA-ROB-006 APIs evolve over time. Version management ensures backward compatibility while enabling innovation:

URL-Based Versioning: Major versions in path (/api/v1/, /api/v2/)
Backward Compatibility: Minor updates (v1.1, v1.2) maintain compatibility within major version
Deprecation Notice: Minimum 12 months notice before endpoint removal
Migration Support: Detailed migration guides, automated conversion tools, parallel operation period
Change Documentation: Comprehensive changelog, API diff tools, breaking change highlights

Version Compatibility Matrix

API Version	Release Date	Status	End of Support	Major Changes
v1.0	2023-01-15	Deprecated	2025-12-31	Initial release
v1.1	2023-06-20	Active	2026-06-30	Added haptic feedback API
v2.0	2024-03-10	Current	TBD	WebRTC streaming, batch operations, improved auth
v2.1	2024-09-15	Current	TBD	AI surgical planning integration

Key Takeaways

RESTful APIs provide standardized endpoints for robot control, instrument manipulation, video streaming, and system monitoring.
WebRTC enables real-time video streaming with <100ms latency, supporting multiple concurrent streams at resolutions up to 4K 60fps.
Haptic feedback API standardizes force/torque data transmission at 100-1000 Hz for future force-reflecting master manipulators.
OAuth 2.0 with role-based access control ensures only authorized users can control surgical robots based on clinical roles.
TLS 1.3 encryption with mutual authentication protects all API communications from eavesdropping and tampering.
WebSocket connections enable low-latency bi-directional communication for telemetry streaming and real-time control.
Safety constraints (velocity limits, force limits, collision avoidance) are enforced at both hardware and software levels.

Review Questions

Explain why WebRTC is preferred over traditional HTTP streaming for surgical video. What latency requirements drive this choice?
Describe the OAuth 2.0 authentication flow for a third-party application accessing surgical robot APIs. What security measures prevent unauthorized access?
Why does haptic feedback require 100-1000 Hz update rates? Calculate the maximum allowable latency for a 1000 Hz haptic loop.
Compare REST APIs vs. WebSocket connections for surgical robot control. When is each approach appropriate?
Design an API call sequence for moving an instrument from position A to position B while avoiding collision with another instrument. Include safety checks.
Explain how role-based access control (RBAC) enhances surgical robot safety. What roles should exist and what permissions should each have?
Analyze the trade-offs between video quality (4K vs 1080p) and network bandwidth requirements. When might lower resolution be acceptable?
Describe error handling strategies for API failures during critical surgical moments. How should the system respond to network interruptions?
Explain how TLS 1.3 with mutual authentication prevents man-in-the-middle attacks on surgical robot APIs.
Design a third-party application that uses WIA-ROB-006 APIs to provide real-time surgical skill assessment. What endpoints would you use and how?