Welche Informationen verbergen sich eigentlich hinter einer API? In der reinen Textausgabe sieht man oft den Wald vor lauter Bäumen nicht — eine sinnvolle Visualisierung muss her. Dazu kann man entweder selbst ein Programm schreiben, um die Daten einzusammeln, aufzubereiten und anschließend grafisch darzustellen, oder ... man verwendet einfach Elasticsearch und Kibana.
Als konkretes Beispiel wollen wir die GitHub API verwenden. Dafür gäbe es sogar ein GitHub Input Plugin für Logstash, aber wir wollen es hier ganz einfach und allgemein anwendbar halten. curl und jq reichen völlig aus, um die Daten auf der Kommandozeile abzurufen und die JSON-Antwort zu verarbeiten und abschließend in Elasticsearch zu speichern.
curl, jq und Elasticsearch
Dazu wollen wir folgendes Shell-Script verwenden, wobei Elasticsearch unter https://<url:ip> erreichbar sein muss und --user '<user>:<password>' muss, falls vorhanden, die richtigen Zugangsdaten enthalten:
#!/bin/bash -e
if (( $# != 1 )); then
printf "Usage: Provide the GitHub username to collect their stats"
exit 1
fi
printf "Fetching data of $1"
printf "\n\nGet the user profile. HTTP return code: "
curl -XGET https://api.github.com/users/$1 --silent | \
jq -c --arg user $1 '{"index": {"_index": "github", "_type": "doc", "_id": .login}}, . + {"type": "user", "github_profile": $user}' | \
curl -XPOST https://<url:ip>/_bulk --silent --write-out '%{http_code}' --output /dev/null --user '<user>:<password>' -H'Content-Type: application/json' --data-binary @-
printf "\n\nGet the user repositories. HTTP return code: "
curl -XGET https://api.github.com/users/$1/repos --silent | \
jq -c --arg user $1 '.[] | {"index": {"_index": "github", "_type": "doc", "_id": .full_name}}, . + {"type": "repo", "github_profile": $user}' | \
curl -XPOST https://<url:ip>/_bulk --silent --write-out '%{http_code}' --output /dev/null --user '<user>:<password>' -H'Content-Type: application/json' --data-binary @-
exit 0
Aufruf und Ausgabe:
$ ./github-userdata.sh xeraa
Fetching data of xeraa
Get the user profile. HTTP return code: 200
Get the user repositories. HTTP return code: 200
Ein paar Anmerkungen zum Script:
- Wer Elasticsearch und Kibana nicht selbst aufsetzen möchte oder die Ergebnisse gerne teilen würde, kann einfach Elastic Cloud verwenden.
- Das Script muss genau mit einem Parameter aufgerufen werden, nämlich dem Benutzernamen dessen GitHub-Daten wir abrufen wollen; beispielsweise
./github-userdata.sh xeraa - Als erstes fragen wir das Benutzerprofil des Users ab und speichern es mit der Bulk API in Elasticsearch. Zusätzlich fügen wir dem abgerufenen Dokument die Attribute
typeundgithub_profile(als jq Parameter übergeben) hinzu, die wir später für Abfragen benötigen. - Danach fragen wir Daten zu den Repositories des Users ab. Einziger Unterschied zur vorigen Abfrage ist, dass wir hier ein Array zurückbekommen, aber jq macht die Verarbeitung mit dem Array-Iterator
.[]ganz einfach. - Die Fehlerbehandlung (existiert der Benutzername, ging bei der Abfrage etwas schief,...) ist auf jeden Fall verbesserungswürdig, aber für ein schnelles Experiment wollen wir es simpel halten.
Für die Daten-Exploration in Kibana habe ich die GitHub-Daten des DevRel-Teams von Elastic verwendet: echo xeraa dadoonet medcl aravindputrevu johtani miiiiiche tylerhannan markwalkom kimjmin ossanna16 eemrich crayzeigh RochelleSonny | xargs -n1 ./github-userdata.sh
Damit wäre das Abrufen, Bearbeiten und Speichern der Daten auch schon fertig.
Kibana
Jetzt können wir uns die Daten ansehen. Zuallererst müssen wir das Index Pattern anlegen: Management → Index Patterns → Create Index Pattern → github
Danach kann man ein passendes Zeitfenster wählen (beispielsweise 8 Years ago) und die Daten in Discover anzeigen. In der nachfolgenden Grafik sind die Daten bereits auf type is user eingeschränkt, um nur die Daten der Benutzerprofile anzuzeigen. Außerdem ist die Ansicht auf einige Columns eingeschränkt um die Anzeige als Tabelle zu ermöglichen:
Wer beim Link zum Benutzer-Avatar das tatsächliche Bild anzeigen möchte, muss folgende Einstellung im Index Pattern auf dem Attribut avatar_url vornehmen:
Anschließend kann man in der Detailansicht den Benutzer-Avatar des jeweiligen Users sehen:
Als nächstes wollen wir uns die Repository-Daten ansehen. Dazu wechseln wir zu Visualize und bauen verschiedene Visualisierungen. Untenstehendes Beispiel zeigt die Summe der Stargazers der top zehn Repositories:
Andere Beispiele könnten die Lizenz, Programmiersprache,... zeigen. Diese kann man anschließend alle in einem Dashboard für alle Benutzer anzeigen:
Über github_profile.keyword is xeraa lassen sich auch die Dashboards auf einen Benutzer einschränken:
Und damit ist unser kurzer Überblick über die GitHub-Profile auch bereits abgeschlossen. Die Beispiele lassen sich natürlich mit mehr Daten und Visualisierungen beliebig erweitern, aber sie können auch leicht auf jede andere HTTP und JSON basierte API angewendet werden.
Frohe Weihnachten und erfolgreiches Erkunden diverser APIs über die Feiertage! 
