Code Examples

Overview Authentication Endpoints Rate Limiting Examples

Bash / cURL Examples

Basic Server Discovery

#!/bin/bash

# Search for US servers running version 1.20
curl -s "https://api.breakblocks.com/api/v0.1/servers/find?country=United%20States&version=1.20&limit=5" \
  -H "Accept: application/json" | jq '.results[] | {ip, port, motd, players}'

Ping Server with cURL

#!/bin/bash

IP="mc.hypixel.net"
PORT="25565"

curl -s "https://api.breakblocks.com/api/v0.1/status/ping/${IP}/${PORT}" | jq '.'

Using API Key in Bash

#!/bin/bash

API_KEY="your_api_key_here"

curl -s "https://api.breakblocks.com/api/v0.1/servers/find?limit=10" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" | jq '.'

JavaScript Examples

Server Discovery with Fetch

// Search for servers
async function searchServers() {
  const response = await fetch(
    'https://api.breakblocks.com/api/v0.1/servers/find?country=United%20States&limit=10'
  );
  const data = await response.json();
  
  data.results.forEach(server => {
    console.log(`${server.ip}:${server.port} - ${server.motd}`);
  });
}

searchServers();

Real-time Server Monitoring

// Monitor multiple servers
const servers = [
  { ip: 'mc.hypixel.net', port: 25565 },
  { ip: 'play.mineplex.com', port: 25565 },
  { ip: 'pvp.hypixel.net', port: 25565 }
];

async function monitorServers() {
  for (const server of servers) {
    try {
      const response = await fetch(
        `https://api.breakblocks.com/api/v0.1/status/ping/${server.ip}/${server.port}`
      );
      const data = await response.json();
      
      if (data.success) {
        console.log(`✓ ${server.ip}: ${data.players.online}/${data.players.max} players`);
      } else {
        console.log(`✗ ${server.ip}: Offline`);
      }
    } catch (error) {
      console.error(`Error pinging ${server.ip}:`, error.message);
    }
    
    // Wait 500ms between requests to avoid rate limiting
    await new Promise(resolve => setTimeout(resolve, 500));
  }
}

// Monitor every 30 seconds
setInterval(monitorServers, 30000);

Fetch with API Key and Error Handling

// Authenticated request with retry logic
async function fetchWithAuth(endpoint, apiKey, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(
        `https://api.breakblocks.com/api/v0.1${endpoint}`,
        {
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
          }
        }
      );
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        console.log(`Rate limited. Waiting ${retryAfter}s...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }
      
      return await response.json();
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error.message);
      if (attempt < maxRetries - 1) {
        await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
      }
    }
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const apiKey = process.env.BREAKBLOCKS_API_KEY;
const data = await fetchWithAuth('/servers/find?limit=10', apiKey);

Get API Key List

// Note: Requires authentication
async function getApiKeys() {
  const response = await fetch(
    'https://api.breakblocks.com/api/v0.1/user/apikeys',
    {
      credentials: 'include' // Include session cookies
    }
  );
  
  const data = await response.json();
  return data.keys;
}

const keys = await getApiKeys();

Python Examples

Server Discovery

import requests

# Search for servers
response = requests.get(
    'https://api.breakblocks.com/api/v0.1/servers/find',
    params={
        'country': 'United States',
        'version': '1.20',
        'limit': 10
    }
)

data = response.json()
for server in data['results']:
    print(f"{server['ip']}:{server['port']} - {server['motd']}")

Server Status Checker

import requests
import time

servers = [
    ('mc.hypixel.net', 25565),
    ('play.mineplex.com', 25565),
]

def check_server_status(ip, port):
    """Check if a server is online"""
    try:
        response = requests.get(
            f'https://api.breakblocks.com/api/v0.1/status/ping/{ip}/{port}',
            timeout=5
        )
        data = response.json()
        
        if data.get('success') and data.get('online'):
            print(f"✓ {ip}: {data['players']['online']}/{data['players']['max']} players")
            return True
        else:
            print(f"✗ {ip}: Offline")
            return False
    except Exception as e:
        print(f"✗ {ip}: Error - {e}")
        return False

# Check all servers
for ip, port in servers:
    check_server_status(ip, port)
    time.sleep(0.5)  # Avoid rate limiting

Authenticated Request with Caching

import requests
import os
import json
from datetime import datetime, timedelta

class BreakBlocksClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://api.breakblocks.com/api/v0.1'
        self.cache = {}
        self.cache_ttl = 300  # 5 minutes
    
    def _is_cached(self, key):
        if key not in self.cache:
            return False
        
        cached_time = self.cache[key]['time']
        if datetime.now() - cached_time > timedelta(seconds=self.cache_ttl):
            del self.cache[key]
            return False
        
        return True
    
    def _make_request(self, endpoint, params=None):
        if self._is_cached(endpoint):
            return self.cache[endpoint]['data']
        
        headers = {'Authorization': f'Bearer {self.api_key}'}
        response = requests.get(
            f'{self.base_url}{endpoint}',
            headers=headers,
            params=params
        )
        
        data = response.json()
        self.cache[endpoint] = {
            'data': data,
            'time': datetime.now()
        }
        
        return data
    
    def find_servers(self, country=None, version=None, limit=10):
        params = {'limit': limit}
        if country:
            params['country'] = country
        if version:
            params['version'] = version
        
        return self._make_request('/servers/find', params)
    
    def ping_server(self, ip, port=25565):
        return self._make_request(f'/status/ping/{ip}/{port}')

# Usage
api_key = os.getenv('BREAKBLOCKS_API_KEY')
client = BreakBlocksClient(api_key)

# First call - fetches from API
servers = client.find_servers(country='United States', limit=5)
print(f"Found {len(servers['results'])} servers")

# Second call within 5 minutes - uses cache
servers = client.find_servers(country='United States', limit=5)
print("Used cached result")

Common Patterns

Retry with Exponential Backoff

// JavaScript - Retry pattern for unreliable networks
async function fetchWithBackoff(url, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const response = await fetch(url);
      if (response.ok) return await response.json();
      
      if (response.status === 429) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Waiting ${delay}ms before retry...`);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (attempt === maxAttempts - 1) throw error;
      
      const backoff = Math.pow(2, attempt) * 1000;
      console.log(`Attempt ${attempt + 1} failed. Retrying in ${backoff}ms...`);
      await new Promise(r => setTimeout(r, backoff));
    }
  }
}

await fetchWithBackoff('https://api.breakblocks.com/api/v0.1/servers/find?limit=10');

Batch Processing with Rate Limit Awareness

// JavaScript - Process many servers while respecting rate limits
async function batchPingServers(servers, requestsPerMinute = 50) {
  const delayBetweenRequests = (60 / requestsPerMinute) * 1000;
  const results = [];
  
  for (const { ip, port } of servers) {
    const response = await fetch(
      `https://api.breakblocks.com/api/v0.1/status/ping/${ip}/${port}`
    );
    
    const data = await response.json();
    results.push(data);
    
    // Check rate limit headers
    const remaining = response.headers.get('X-RateLimit-Remaining');
    const reset = response.headers.get('X-RateLimit-Reset');
    
    console.log(`Requests remaining: ${remaining} (resets at ${new Date(reset * 1000)})`);
    
    // Wait before next request
    await new Promise(r => setTimeout(r, delayBetweenRequests));
  }
  
  return results;
}

const servers = [
  { ip: 'server1.com', port: 25565 },
  { ip: 'server2.com', port: 25565 }
  // ... more servers
];

const results = await batchPingServers(servers, 40);  // 40 requests/minute