Skip to main content

REST API

The Rest class handles HTTP communication with the Lavalink server. It provides methods for track loading, player management, session management, and server information.

Constructor​

import { Rest } from 'yukinojs';

const rest = new Rest({
url: 'localhost:2333',
auth: 'your-password',
secure: false, // Use HTTPS
timeout: 15000, // Request timeout in ms
version: '4', // Lavalink API version
debug: false // Enable debug logging
});

Track Loading​

loadTracks(identifier: string, source?: string)​

Load tracks from URLs or search queries. Optionally specify a search source (default: 'ytsearch').

// Load from URL
const result = await rest.loadTracks('https://youtube.com/watch?v=...');

// Search YouTube
const searchResult = await rest.loadTracks('ytsearch:your search query');

// Specify a custom source
const scResult = await rest.loadTracks('your search', 'scsearch');

// Handle different result types
switch (result.loadType) {
case 'track':
console.log('Single track:', result.data[0].info.title);
break;
case 'playlist':
console.log('Playlist:', result.playlistInfo?.name);
console.log('Track count:', result.data?.length);
break;
case 'search':
console.log('Search results:', result.data?.length);
break;
case 'empty':
console.log('No matches found');
break;
case 'error':
console.error('Error:', result.exception?.message);
break;
}

decodeTrack(encodedTrack: string)​

Decode a base64 track string into track information.

const trackInfo = await rest.decodeTrack('base64trackstring...');
console.log('Track title:', trackInfo.title);

encodeTrack(track: Record<string, any>)​

Encode track information into a base64 string.

const encoded = await rest.encodeTrack({
title: 'Song Name',
author: 'Artist',
length: 180000
});

Player Management​

updatePlayer(sessionId: string, guildId: string, data: any)​

Update a player's state via REST API.

await rest.updatePlayer('session-id', 'guild-id', {
track: {
encoded: 'base64track...'
},
volume: 100,
paused: false
});

getPlayer(sessionId: string, guildId: string)​

Get information about a specific player.

const player = await rest.getPlayer('session-id', 'guild-id');
console.log('Current track:', player.track);

getPlayers(sessionId: string)​

Get all players in a session.

const players = await rest.getPlayers('session-id');
console.log('Active players:', players.length);

destroyPlayer(sessionId: string, guildId: string)​

Destroy a player instance.

await rest.destroyPlayer('session-id', 'guild-id');

destroyAllPlayers(sessionId: string)​

Destroy all players for a session.

await rest.destroyAllPlayers('session-id');

updateVoiceServer(sessionId: string, guildId: string, voiceUpdate: { token: string; endpoint: string; sessionId: string })​

Update the voice server data for a guild.

await rest.updateVoiceServer('session-id', 'guild-id', {
token: 'voice-token',
endpoint: 'voice-endpoint',
sessionId: 'voice-session-id'
});

Session Management​

updateSession(sessionId: string, resumeKey: string, timeout?: number)​

Update session configuration for resuming.

await rest.updateSession(
'session-id',
'resume-key',
60 // Resume timeout in seconds
);

getSessions()​

Get all active Lavalink sessions.

const sessions = await rest.getSessions();
console.log('Active sessions:', sessions.length);

getSession(sessionId: string)​

Get information about a specific session.

const session = await rest.getSession('session-id');
console.log('Session details:', session);

Server Information​

version()​

Get Lavalink server version.

const version = await rest.version();
console.log('Lavalink version:', version);

info()​

Get detailed server information.

const info = await rest.info();
console.log('Server info:', info);

stats()​

Get server statistics.

const stats = await rest.stats();
console.log('CPU Usage:', stats.cpu.systemLoad);
console.log('Memory Used:', stats.memory.used);

Generic HTTP Methods​

The Rest class also provides generic HTTP methods for advanced use:

  • get<T>(url: string, customHeaders?)
  • post<T>(url: string, data?, customHeaders?)
  • patch<T>(url: string, data?, customHeaders?)
  • delete<T>(url: string, customHeaders?)
  • request<T>(endpoint: string, method = 'GET', body?, customHeaders?)

Error Handling​

The REST client includes comprehensive error handling for all HTTP methods:

try {
await rest.loadTracks('invalid://url');
} catch (error) {
console.error('Status:', error.response?.status);
console.error('Message:', error.response?.data);
}

Debug Mode​

When debug mode is enabled:

const rest = new Rest({
url: 'localhost:2333',
auth: 'password',
debug: true // Enable debug logging
});

You'll see detailed logs for:

  • All HTTP requests and responses
  • Request timing information
  • Error details with stack traces
  • Decoded track information
  • Server status updates

Request Configuration​

Base Configuration​

const rest = new Rest({
url: 'localhost:2333',
auth: 'password',
secure: false,
timeout: 15000,
version: '4'
});

Using HTTPS​

const rest = new Rest({
url: 'example.com:2333',
auth: 'password',
secure: true // Use HTTPS
});

Custom Timeout​

const rest = new Rest({
url: 'localhost:2333',
auth: 'password',
timeout: 30000 // 30 seconds
});

Best Practices​

  1. Handle rate limits gracefully:
async function loadTrackWithRetry(identifier: string, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await rest.loadTracks(identifier);
} catch (error) {
if (error.response?.status === 429) {
const retryAfter = error.response.headers['retry-after'];
await new Promise(r => setTimeout(r, retryAfter * 1000));
continue;
}
throw error;
}
}
}
  1. Process REST events properly:
rest.processRestEvents(node, response);
  1. Use timeouts appropriately:
const rest = new Rest({
url: 'localhost:2333',
auth: 'password',
timeout: 15000 // Default
});

// For long operations
rest.timeout = 30000;