DartHub Public API v1

Turniere eines Vereins im eigenen Webdesign anzeigen

Die API liefert JSON und benötigt immer einen API-Schlüssel. Schlüssel erstellt ein Vereins-Owner oder -Admin in DartHub unter Verein → Öffentliche API.

Basis-URL

https://www.darthub.ch/api/v1/public

Der Schlüssel wird ausschliesslich im Header übertragen:

X-DartHub-Key: dhpk_…

Schlüsselarten

ArtVerwendungSchutz
dhpk_… BrowserDirekter Abruf aus JavaScriptBis zu drei erlaubte Domains; gültiger Origin erforderlich
dhsk_… ServerPHP, WordPress oder anderes BackendGeheim halten; nicht an den Browser senden

Endpunkte

GET /clubs
GET /clubs/{slug}/events?state=live,upcoming&limit=10
GET /events/{id}

/clubs liefert nur den Verein des verwendeten Schlüssels. Ereignis-IDs sind typisiert: evt_131 für Standard-/Trainingsturniere und pyr_3 für Pyramiden.

Beispiel

fetch('https://www.darthub.ch/api/v1/public/clubs/mein-verein/events?state=live,upcoming&limit=10', {
  headers: {'X-DartHub-Key': 'dhpk_…'}
}).then(r => r.json()).then(console.log);

Antworten enthalten data und meta. Ein Ereignis liefert Titel, Typ, Status, Ort sowie unverändert zu verwendende DartHub-Links. Spielstände, Legs, Sets, Ranglisten und abgeschlossene Turniere werden nicht ausgegeben.

Teilnehmerlisten

Die Detailantwort enthält participants.list nur, wenn die Turnierleitung reg_list_public = 1 gesetzt hat. Verknüpfte Konten erscheinen als Nachname Vorname (Spitzname), Gäste als Nachname Vorname. E-Mail-Adressen werden nie ausgegeben.

Fehler und Limits

401Schlüssel fehlt oder ist ungültig
403Domain oder Verein nicht freigegeben
404Verein oder Ereignis nicht gefunden
42960 Anfragen pro Minute überschritten; Retry-After beachten

Antworten dürfen 60 Sekunden zwischengespeichert werden. Bei einem Ausfall sollte die externe Seite den API-Bereich ausblenden und weiterhin normal funktionieren.

Vier Einbaubeispiele

Wähle die passende Einbindung, lies die drei Schritte und öffne danach den vollständigen Quellcode. Die angezeigte Fassung wird direkt aus der jeweiligen Beispieldatei geladen.

Kachelliste für Browser

Browser / HTML und JavaScript

Zeigt laufende und bevorstehende Turniere als Karten auf einer normalen Vereinswebseite.

  1. Browser-Schlüssel mit der Domain der Vereinswebseite erstellen.
  2. API_KEY und CLUB_SLUG im Quellcode ersetzen.
  3. HTML, CSS und JavaScript in die gewünschte Webseite übernehmen.
Vollständigen Quellcode anzeigen
<!doctype html>
<html lang="de">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>DartHub – Turnierkarten</title>
<style>
#darthub-events{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:1rem}
.dh-event{padding:1rem;border:1px solid #ddd;border-radius:.75rem}.dh-event a{font-weight:700}
</style></head>
<body>
<section id="darthub-events" aria-live="polite"></section>
<script>
const API_BASE='https://www.darthub.ch/api/v1/public';
const API_KEY='dhpk_HIER_BROWSER_SCHLUESSEL_EINSETZEN';
const CLUB_SLUG='mein-verein';

async function loadDartHubEvents(){
  const box=document.getElementById('darthub-events');
  try{
    const response=await fetch(`${API_BASE}/clubs/${encodeURIComponent(CLUB_SLUG)}/events?state=live,upcoming&limit=10`,{
      headers:{'X-DartHub-Key':API_KEY}
    });
    if(!response.ok) throw new Error('API '+response.status);
    const payload=await response.json();
    box.replaceChildren(...payload.data.map(event=>{
      const article=document.createElement('article');
      article.className='dh-event';
      const title=document.createElement('h3'); title.textContent=event.title;
      const state=document.createElement('p'); state.textContent=event.state.text;
      const link=document.createElement('a'); link.href=event.live_url; link.textContent='Live auf DartHub ansehen';
      link.target='_blank'; link.rel='noopener';
      article.append(title,state,link); return article;
    }));
    box.hidden=payload.data.length===0;
  }catch(error){box.hidden=true;console.warn('DartHub derzeit nicht erreichbar.',error);}
}
loadDartHubEvents();
</script>
</body></html>

Live-Hinweisstreifen für Browser

Browser / HTML und JavaScript

Blendet nur dann einen Hinweis ein, wenn gerade ein Turnier oder eine Pyramide live ist. Die Abfrage wird einmal pro Minute wiederholt.

  1. Browser-Schlüssel mit der Domain der Vereinswebseite erstellen.
  2. API_KEY und CLUB_SLUG im Quellcode ersetzen.
  3. Den Link und das Skript an der gewünschten Stelle einbauen.
Vollständigen Quellcode anzeigen
<!doctype html>
<html lang="de">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>DartHub – Live-Hinweis</title>
<style>#darthub-live{display:block;padding:.8rem 1rem;background:#ff7a00;color:#111;border-radius:.6rem;font-weight:700}#darthub-live[hidden]{display:none}</style>
</head><body>
<a id="darthub-live" hidden target="_blank" rel="noopener"></a>
<script>
const API_BASE='https://www.darthub.ch/api/v1/public';
const API_KEY='dhpk_HIER_BROWSER_SCHLUESSEL_EINSETZEN';
const CLUB_SLUG='mein-verein';

async function loadDartHubLiveBanner(){
  const banner=document.getElementById('darthub-live');
  try{
    const response=await fetch(`${API_BASE}/clubs/${encodeURIComponent(CLUB_SLUG)}/events?state=live&limit=1`,{
      headers:{'X-DartHub-Key':API_KEY}
    });
    if(!response.ok) throw new Error('API '+response.status);
    const payload=await response.json(), event=payload.data[0];
    if(!event){banner.hidden=true;return;}
    banner.textContent=`Jetzt läuft: ${event.title} – live ansehen`;
    banner.href=event.live_url; banner.hidden=false;
  }catch(error){banner.hidden=true;console.warn('DartHub derzeit nicht erreichbar.',error);}
}
loadDartHubLiveBanner();
setInterval(loadDartHubLiveBanner,60000);
</script>
</body></html>

Serverseitiges PHP-Beispiel

Server / PHP

Ruft Turniere im PHP-Backend ab. Der geheime Schlüssel bleibt auf dem Server und wird nicht an Besucher ausgeliefert.

  1. Server-Schlüssel erstellen und sicher auf dem Webserver hinterlegen.
  2. Umgebungsvariable DARTHUB_SERVER_KEY setzen.
  3. Vereins-Slug in $clubSlug eintragen und die Ausgabe ans eigene Design anpassen.
Vollständigen Quellcode anzeigen
<?php
declare(strict_types=1);

$apiBase = 'https://www.darthub.ch/api/v1/public';
$clubSlug = 'mein-verein';
$serverKey = getenv('DARTHUB_SERVER_KEY') ?: '';
if ($serverKey === '') {
    http_response_code(500);
    exit('DARTHUB_SERVER_KEY ist nicht konfiguriert.');
}

$url = $apiBase . '/clubs/' . rawurlencode($clubSlug) . '/events?state=live,upcoming&limit=10';
$curl = curl_init($url);
curl_setopt_array($curl, array(
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
    CURLOPT_HTTPHEADER => array('X-DartHub-Key: ' . $serverKey, 'Accept: application/json'),
));
$body = curl_exec($curl);
$status = (int)curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
$payload = is_string($body) ? json_decode($body, true) : null;
$events = ($status === 200 && is_array($payload['data'] ?? null)) ? $payload['data'] : array();

foreach ($events as $event) {
    $title = htmlspecialchars((string)($event['title'] ?? ''), ENT_QUOTES, 'UTF-8');
    $state = htmlspecialchars((string)($event['state']['text'] ?? ''), ENT_QUOTES, 'UTF-8');
    $liveUrl = htmlspecialchars((string)($event['live_url'] ?? ''), ENT_QUOTES, 'UTF-8');
    echo "<article><h3>{$title}</h3><p>{$state}</p><a href=\"{$liveUrl}\" target=\"_blank\" rel=\"noopener\">Live ansehen</a></article>\n";
}

WordPress-Shortcode

Server / WordPress

Stellt den Shortcode [darthub_events] bereit und lädt die Turnierliste serverseitig über WordPress.

  1. Code in ein kleines Plugin oder in die functions.php eines Child-Themes übernehmen.
  2. DARTHUB_SERVER_KEY sicher in wp-config.php definieren.
  3. Shortcode als [darthub_events club="mein-verein"] in eine Seite einsetzen.
Vollständigen Quellcode anzeigen
<?php
/**
 * In ein kleines Plugin oder in die functions.php eines Child-Themes übernehmen.
 * Den geheimen Schlüssel bevorzugt in wp-config.php definieren:
 * define('DARTHUB_SERVER_KEY', 'dhsk_...');
 */
add_shortcode('darthub_events', function (array $attributes): string {
    $attributes = shortcode_atts(array('club' => 'mein-verein', 'limit' => '10'), $attributes);
    $key = defined('DARTHUB_SERVER_KEY') ? DARTHUB_SERVER_KEY : '';
    if ($key === '') return '';

    $limit = max(1, min(50, (int)$attributes['limit']));
    $url = 'https://www.darthub.ch/api/v1/public/clubs/' . rawurlencode($attributes['club'])
        . '/events?state=live,upcoming&limit=' . $limit;
    $response = wp_remote_get($url, array(
        'timeout' => 5,
        'headers' => array('X-DartHub-Key' => $key, 'Accept' => 'application/json'),
    ));
    if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) return '';

    $payload = json_decode(wp_remote_retrieve_body($response), true);
    if (!is_array($payload['data'] ?? null) || !$payload['data']) return '';

    $html = '<div class="darthub-events">';
    foreach ($payload['data'] as $event) {
        $html .= '<article class="darthub-event"><h3>' . esc_html($event['title'] ?? '') . '</h3>'
            . '<p>' . esc_html($event['state']['text'] ?? '') . '</p>'
            . '<a href="' . esc_url($event['live_url'] ?? '') . '" target="_blank" rel="noopener">Live ansehen</a></article>';
    }
    return $html . '</div>';
});

Browser-Schlüssel dürfen nur auf ihren freigegebenen Domains verwendet werden. Server-Schlüssel gehören in eine Umgebungsvariable oder Serverkonfiguration, niemals in öffentliches JavaScript.