Skip to content

API.md

Latest commit

 

History

History
337 lines (266 loc) · 7.12 KB

API.md

File metadata and controls

337 lines (266 loc) · 7.12 KB

API Documentation

Overview

This document describes the API endpoints and Socket.io events for the Live Loop video calling application.

Base URL

Development: http://localhost:3000
Production: https://your-domain.com

REST API Endpoints

Health Check

Check if the server is running and healthy.

Endpoint: GET /

Response:

{
  status: "OK",
  message: "Hello, TypeScript!"
}

System Status

Get current system status including queue and room information.

Endpoint: GET /api/status

Response:

{
  queue: {
    size: 5,
    users: ["user1", "user2", "user3"]
  },
  rooms: {
    active: 10,
    total: 15
  },
  timestamp: "2025-01-17T10:00:00Z"
}

Socket.io Events

Client to Server Events

request-room

Request to join a room and find a match.

Event: request-room

Payload:

{
  name: string,           // User's display name
  roomId: string | null,  // Previous room ID (if rejoining)
  userImage: string       // Base64 encoded user thumbnail
}

Description: Adds user to the matchmaking queue and attempts to find a match.

negotiation-call-offer

Send WebRTC offer to establish peer connection.

Event: negotiation-call-offer

Payload:

{
  offer: RTCSessionDescriptionInit,  // WebRTC offer
  roomId: string,                    // Room identifier
  name: string,                      // User's name
  remoteSocketId: string             // Target user's socket ID
}

negotiation-call-answer

Send WebRTC answer to complete peer connection.

Event: negotiation-call-answer

Payload:

{
  ans: RTCSessionDescriptionInit,    // WebRTC answer
  roomId: string,                    // Room identifier
  name: string,                      // User's name
  remoteSocketId: string             // Target user's socket ID
}

send-new-ice-candidates

Send ICE candidates for NAT traversal.

Event: send-new-ice-candidates

Payload:

{
  to: string,                        // Target socket ID
  candidate: RTCIceCandidate         // ICE candidate
}

stop-call

End the current call session.

Event: stop-call

Payload:

{
  roomId: string,                    // Room identifier
  remoteSocketId: string,            // Remote user's socket ID
  name: string                       // User's name
}

newMessage

Send a chat message during the call.

Event: newMessage

Payload:

{
  message: string,                   // Chat message content
  roomId: string,                    // Room identifier
  remoteSocket: string               // Remote user's socket ID
}

Server to Client Events

match-done

Notify that a match has been found.

Event: match-done

Payload:

{
  roomId: string,                    // Room identifier
  remoteUserDetails: {
    socket: string,                  // Remote user's socket ID
    userName: string,                // Remote user's name
    userImage: string                // Remote user's thumbnail
  }
}

negotiation-call-offer

Receive WebRTC offer from remote user.

Event: negotiation-call-offer

Payload:

{
  remoteUserDetails: {
    socket: string,                  // Remote user's socket ID
    userName: string                 // Remote user's name
  },
  roomId: string,                    // Room identifier
  offer: RTCSessionDescriptionInit   // WebRTC offer
}

negotiation-call-answer

Receive WebRTC answer from remote user.

Event: negotiation-call-answer

Payload:

{
  ans: RTCSessionDescriptionInit,    // WebRTC answer
  roomId: string,                    // Room identifier
  name: string,                      // Remote user's name
  remoteSocketId: string             // Remote user's socket ID
}

new-ice-candidates

Receive ICE candidates from remote user.

Event: new-ice-candidates

Payload:

{
  candidate: RTCIceCandidate         // ICE candidate
}

stop-by-remote-user

Notification that the remote user ended the call.

Event: stop-by-remote-user

Payload: None

Message:recived

Receive a chat message from remote user.

Event: Message:recived

Payload:

{
  from: string,                      // Sender's socket ID
  message: string                    // Message content
}

Connection Flow

1. Initial Connection

Client connects → Server assigns socket ID → Client joins general room

2. Matchmaking Flow

Client: request-room
    ↓
Server: Adds to queue → Attempts matching
    ↓
Server: match-done (to both users)
    ↓
Clients: Setup WebRTC connection

3. WebRTC Signaling Flow

User A: negotiation-call-offer
    ↓
Server: Forward to User B
    ↓
User B: negotiation-call-answer
    ↓
Server: Forward to User A
    ↓
Both users exchange ICE candidates
    ↓
P2P connection established

4. Chat Flow

User A: newMessage
    ↓
Server: Broadcast to both users
    ↓
Both users: Message:recived

5. Call Termination

User A: stop-call
    ↓
Server: stop-by-remote-user (to User B)
    ↓
Both users: Clean up connections
    ↓
Server: Re-add users to queue (optional)

Error Handling

Connection Errors

  • Connection timeout: Automatic reconnection attempt
  • Invalid room: Error message to user
  • Queue full: User notified to try again later

WebRTC Errors

  • Offer/Answer failure: Connection retry
  • ICE candidate failure: Fallback to TURN server
  • Media access denied: User notification

Chat Errors

  • Message delivery failure: Retry mechanism
  • Invalid message format: Client-side validation

Rate Limiting

Socket Events

  • request-room: 1 request per 5 seconds
  • newMessage: 10 messages per minute
  • ICE candidates: No limit (essential for connectivity)

Best Practices

  1. Always handle event errors gracefully
  2. Implement reconnection logic for socket disconnections
  3. Validate all payloads before sending
  4. Clean up resources when connections end
  5. Use appropriate timeouts for WebRTC operations

Testing

Socket.io Testing

// Example test using socket.io-client
const io = require('socket.io-client');
const client = io('http://localhost:3000');

client.emit('request-room', {
  name: 'Test User',
  roomId: null,
  userImage: 'data:image/png;base64,...'
});

client.on('match-done', (data) => {
  console.log('Match found:', data);
});

WebRTC Testing

// Test WebRTC offer creation
const peerConnection = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' }
  ]
});

const offer = await peerConnection.createOffer();
await peerConnection.setLocalDescription(offer);