Faceit-API – Erklärung + Praxisbeispiel

In diesem Beitrag möchte ich dir die API von Faceit etwas näher bringen. Was kann man mit Ihr machen, wozu ist sie gut und vor allem, wie verwende ich sie korrekt? Das sind Fragen, mit denen wir uns jetzt auseinandersetzen.

Was ist die Faceit-API?

Ich müsste dazu erstmal erklären, was eine API ist. API steht für „Application Programming Interface“, welches im Endeffekt eine Programmierschnittstelle ist. Die Faceit-API ist eine Benutzerschnittstelle, sodass Entwickler auf bestimmte Bereiche und Daten von Faceit zugreifen können, um diese für eigene Projekte (wie in meinem Beispiel) wie Websites oder Software zu verwenden.

Ohne diese API könnte ich keine Nutzerinformationen zu Accounts auslesen. Solche APIs werden auch von großen Firmen und Projekten genutzt. Prominente Beispiele für solche APIs sind unter anderem die Integrationen von Paypal in Online-Shops, damit du z. B. bei Zalando auch mit Paypal bezahlen kannst oder die Logins von sozialen Netzwerken wie Google, Facebook oder Twitter auf Webseiten.

Teil 1 – Die Vorbereitungen

Heute soll es aber um die Faceit-API gehen und ich möchte dir nun zeigen, wie man diese korrekt anwendet. Zuerst muss man sich dafür im Developer Portal von Faceit anmelden. Dort erstellen wir eine App im App Studio.

Wie du die App nennst, liegt ganz bei dir. Wichtig ist dies eigentlich nur, falls es sich um ein gemeinsames Projekt mit einem anderen Programmierer handelt. Auch die Beschreibung ist relativ irrelevant. Sobald die App fertig erstellt ist, wirst du zu der Detailübersicht deiner neuen App weitergeleitet.

Wichtig ist hierbei aber nicht die Detailansicht, sondern die API-Keys, welche man unter dem Tab API KEYS erstellen muss. Das sind gewissermaßen unsere Passwörter, um die API nutzen zu können.

Um deinen API-Key zu erstellen, wechselst du in den Reiter API KEYS und klickst dort auf das orange Plussymbol. Anschließend wählst du bei Type „Server side“ aus und klickst auf CREATE. Wenn du alles richtig gemacht hast, erhältst du eine dementsprechende Meldung.

Wie bereits im oberen Abschnitt beschrieben, nutzen wir für unser Beispiel den serverseitigen Key, welcher für serverseitige Sprachen wie PHP, Python oder Ruby verwendet wird. Der clientseitige Key ist für Sprachen wie JavaScript gedacht.

Für unser Script nutzen wir simples PHP inklusive cURL. Je nach Projekt kann man natürlich zum Beispiel auch mit Datenbanken arbeiten. Ich würde sagen, wir uns jetzt endlich an die API trauen und mit dem Programmieren beginnen.

Teil 2 – Die Programmierarbeit

Legen wir zuerst fest, welche Informationen wir abfragen möchten. Je nach Endpoint der API bekommen wir verschiedene Informationen im JSON-Format ausgegeben. Ich möchte in diesem Beispiel meinen Avatar, meine SteamID, mein Skilllevel und die Elo abfragen und anschließend ausgeben lassen.

Die Auswahl der Endpoints fällt mir dank der wirklich sehr übersichtlichen Dokumentation von Faceit sehr einfach. Da ich Informationen über Spieler abfragen möchte, aber keine Informationen über die Faceit-ID des Spielers besitze, bin ich auf den Endpoint /players angewiesen.

Der korrekte cURL-Request dafür sieht folgendermaßen aus.

curl -X GET "https://open.faceit.com/data/v4/players?nickname=Mojinho" -H "accept: application/json" -H "Authorization: Bearer 411ea515-4f59-4d4c-8ea6-7be6b6c8e93e"

Nur wie setzen wir das in einer Website um? Das zeige ich dir nun Schritt für Schritt.

Zuerst erstellen wir eine neue Datei und nennen diese einfach faceitapi.php. Anschließend öffnen und schließen wir die PHP-Tags. Innerhalb der PHP-Tags definieren wir als Erstes den Nickname des Spielers, über den wir die Informationen erfragen wollen.

<?php

    // store all relevant data
    $nickname = "Mojinho";

?>

In echten Projekten werden diese Namen entweder über ein Formular übergeben, oder aus der Datenbank abgefragt. Da dies hier nur ein Beispiel ist, spare ich mir die Arbeit.

Bevor wir den cURL-Request durchführen, bin ich immer ein Freund von „error handling“. Ich prüfe also noch vor meinem Request, ob die cURL-Erweiterung überhaupt auf dem Server installiert ist. Das hat den einfachen Hintergrund, dass ich im Falle des Falles eine Meldung darüber bekommen würde und nicht ewig nach einem Fehler in meinem Code suchen würde.

<?php

    // store all relevant data
    $nickname = "Mojinho";

    // cURL error handling
    if(!extension_loaded("curl")) {
        die("cURL extension not installed. Please install this extension!");
    }

?>

Nun folgt der cURL-Request über die API. Dazu speichern wir den String der URL in der Variable $url ab, initialisieren einen Request, setzen unseren Autorisierungsschlüssel im HTTP-Header fest und führen den Request durch.

Erinnerst du dich daran, dass ich erwähnte, dass wir die Informationen im JSON-Format ausgegeben bekommen? Dementsprechend dürfen wir im Anschluss nicht vergessen, die JSON-Ausgabe mittels json_decode() zu dekodieren.

Davor müssen wir uns allerdings erst einmal die Struktur des Response-Bodys anschauen, welchen man in der Dokumentation des Developer-Portals findet. Das Beispiel habe ich zweckdienlich gekürzt.

{
  "avatar": "string",
  "country": "string",
  "cover_featured_image": "string",
  "cover_image": "string",
  "faceit_url": "string",
  "friends_ids": [
    "string"
  ],
  "games": {
    "additionalProp1": {
      "faceit_elo": 0,
      "game_player_id": "string",
      "game_player_name": "string",
      "game_profile_id": "string",
      "region": "string",
      "regions": {},
      "skill_level": 0,
      "skill_level_label": "string"
    }
  }
}

Wie bereits weiter oben erwähnt, werden wir jetzt den Request durchführen und die JSON-Ausgabe mittels json_decode() dekodieren. Dafür werden die von uns gewünschten Daten (Avatar, SteamID, Skill Level und Elo) in Variablen eingespeichert.

Allerdings müssen wir dafür auf die richtige Struktur zugreifen können, da die Informationen in verschiedenen JSON-Arrays und JSON-Objekten gespeichert sind. Das sieht dann folgendermaßen aus.

<?php

    // store all relevant data
    $nickname = "Mojinho";

    // cURL error handling
    if(!extension_loaded("curl")) {
        die("cURL extension not installed. Please install this extension!");
    }

	$url = "https://open.faceit.com/data/v4/players?nickname=".$nickname;
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array("Authorization: Bearer 411ea515-4f59-4d4c-8ea6-7be6b6c8e93e"));
    curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
    $out = curl_exec($curl);
    curl_close($curl);
    $decoded = json_decode($out);
    
    $faceitAvatar       = $decoded->{'avatar'};
    $faceitSteamID      = $decoded->{'platforms'}->{'steam'};
    $faceitSkillLevel   = $decoded->{'games'}->{'csgo'}->{'skill_level'};
    $faceitElo          = $decoded->{'games'}->{'csgo'}->{'faceit_elo'};

?>

Wenn wir unser Script im Browser über den Localhost öffnen und eine komplett weiße Seite erhalten, dann hast du bislang alles richtig gemacht. Die cURL-Bibliothek ist installiert, die Verbindung wurde erfolgreich hergestellt und die Daten erfolgreich in den Variablen gespeichert.

Um dies final zu verifizieren, lasse ich diese noch kurz im Browser ausgeben. Dort kannst du deine Fantasie spielen lassen. Rein theoretisch sind dir hier keine Grenzen gesetzt. Eine wirklich optisch sehr ansprechende Website auf der Basis der Faceit-API ist faceitstats.com.

Ich habe für dieses Beispiel einfach ein bisschen mit Bootstrap gespielt. Daher kannst du dir diesen Code einfach wegdenken. Das wichtige ist hierbei nur, wie die PHP-Variablen wieder eingesetzt wurden. Hier nun der fertige Code mit abschließendem Screenshot des Ergebnisses.

Vollständiger Code

<?php

    // store all relevant data
    $nickname = "Mojinho";

    // cURL error handling
    if(!extension_loaded("curl")) {
        die("cURL extension not installed. Please install this extension!");
    }

    $url = "https://open.faceit.com/data/v4/players?nickname=".$nickname;
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array("Authorization: Bearer 411ea515-4f59-4d4c-8ea6-7be6b6c8e93e"));
    curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
    $out = curl_exec($curl);
    curl_close($curl);
    $decoded = json_decode($out);
    
    $faceitAvatar       = $decoded->{'avatar'};
    $faceitSteamID      = $decoded->{'platforms'}->{'steam'};
    $faceitSkillLevel   = $decoded->{'games'}->{'csgo'}->{'skill_level'};
    $faceitElo          = $decoded->{'games'}->{'csgo'}->{'faceit_elo'};
?>

<!DOCTYPE html>
<html lang="de">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Faceit-API Beispiel</title>

    <!-- Bootstrap CDN -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
</head>
<body class="bg-dark">
    <div class="container-fluid">
        <div class="row">
            <div class="col d-flex justify-content-center mt-5">
                <div class="card" style="width: 18rem;">
                    <img src="<?php echo $faceitAvatar; ?>" class="card-img-top" alt="...">
                    <div class="card-body">
                        <h5 class="card-title text-center"><?php echo $nickname; ?></h5>
                        <p class="card-text">
                            <?php
                                echo "SteamID: " . $faceitSteamID . "<br>";
                                echo "Skill Level: " . $faceitSkillLevel . "<br>";
                                echo "Elo: " . $faceitElo;
                            ?>
                        </p>
                    </div>
                </div>
            </div>
        </div>
    </div>
</body>
</html>

Screenshot des Ergebnisses

Fazit

Das war es auch schon! Das war doch einfacher als erwartet, oder? Ich hoffe, dass ich dir mit diesem Tutorial zur Faceit-API bei deinem zukünftigen Projekt weiterhelfen konnte. Solltest du weitere Fragen haben, freue mich darauf, diese zu beantworten – Maurice.