Skip to content

Home

Jump to bottom
Marcus Jaschen edited this page Nov 26, 2021 · 51 revisions

API-Dokumentation

Wir bieten für den Winterpokal auf MTB-News.de und Rennrad-News.de ein HTTP-API an.

Es ist damit möglich, Daten aus dem Winterpokal auszulesen und neue Einträge anzulegen.

Letzte Aktualisierung: 2021-11-26

Neu in der Saison 2021/2022

  • 2021-11-01: Neu: Unterstützung für das commute-Flag von Einträgen
  • 2021-11-01: Neu: Unterstützung für die neue Kategorie schwimmen

Neu in der Saison 2016/2017

  • 2016-11-07: Nach dem Hinzufügen eines Eintrags werden die kompletten Daten des Eintrags sowie die aktualisierten Benutzerdaten zurückgeliefert
  • 2016-10-11: Unterstützung für das nightride-Flag von Einträgen

Neu in der Saison 2015/2016

  • 2015-11-16: Unterstützung für die Distanz von Einträgen
  • Das Strava-Ranking kann abgerufen werden; es berücksichtigt nur die Einträge, die über den Strava-Import gemacht wurden.
  • Die Rankings der vorherigen Winterpokale können abgerufen werden, zurück bis zur Saison 2008/2009.
  • Die Einträge der vorherigen Winterpokale können abgerufen werden, zurück bis zur Saison 2008/2009.
  • In der Dokumentation der Team-Favoriten-Abfrage wurde ein Fehler in der Beschreibung des Response-Formats behoben.

Projekte welche die API-Funktionen nutzen

Wenn ihr ein Projekt habt, welche die API-Funktionen nutzt: sagt Bescheid, wir verlinken euch hier!

API-Funktionen

Authentifizierung

Die Authentifizierung geschieht über ein Token, welches in den Headerdaten des HTTP-Requests mitgeschickt werden muss.

Der Request-Header für das Token lautet api-token.

Ohne dieses Token können keine API-Funktionen benutzt werden.

Das Token ist ein 36 Zeichen langer String, welcher einen Benutzer eindeutig identifiziert. Jeder Benutzer kann bis zu fünf Token besitzen und diese jederzeit auch wieder löschen und sie damit ungültig machen.

Das Token ist mit der gleichen Vorsicht wie ein Password zu behandeln.

Die API-Tokens können hier verwaltet werden: https://winterpokal.mtb-news.de/api-keys, https://winterpokal.rennrad-news.de/api-keys oder https://winterpokal.emtb-news.de/api-keys

Es ist möglich, die Tokens eines Users auch per speziellem API-Request abzurufen. Dazu muss der Client sich mit Benutzername oder E-Mail-Adresse sowie dem Kennwort authentifizieren.

Beispiele

curl-Command-Line-Tool:

curl -H 'api-token: DFHDGFEHGDHFBXCBXSRTHGBDBNBDBQETSSAG' \
https://winterpokal.mtb-news.de/api/v1/entries/user/257.json?limit=5

httpie-Command-Line-Tool:

http winterpokal.mtb-news.de/api/v1/entries/user/257.json?limit=5 api-token:DFHDGFEHGDHFBXCBXSRTHGBDBNBDBQETSSAG

PHP-Beispielskript:

<?php
// initialize curl ressource handle
$c = curl_init('https://winterpokal.mtb-news.de/api/v1/entries/user/257.json?limit=1');

// set API token header
curl_setopt(
    $c,
    CURLOPT_HTTPHEADER,
    array('api-token: DFHDGFEHGDHFBXCBXSRTHGBDBNBDBQETSSAG')
);

// store the response body into a variable instead of directly printing it
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);

// execute the request
$result = curl_exec($c);

if (false === $result) {
    throw new RuntimeException('ERR_CURL_REQUEST_FAILED');
}

$parsed_result = json_decode($result);

if (null === $parsed_result) {
    throw new RuntimeException('ERR_CANNOT_DECODE_RESPONSE');
}

print_r($parsed_result);

Rate-Limiting

Noch nicht.

Datenformat

Die API liefert die Daten im JSON-Format. POST-Daten an die API werden ebenfalls in JSON erwartet.

URLs

Info: Der Winterpokal auf rennrad-news.de bietet die selben API-Funktionen. In den URLs muss lediglich mtb-news.de durch rennrad-news.de ersetzt werden. Analog gilt das für emtb-news.de.

Info: Die API-Funktionen sind ausschließlich über HTTPS erreichbar.

Die API-Funktionen können folgendermaßen angesprochen werden:

https://winterpokal.mtb-news.de/api/v1/<TYPE>/<METHOD>.json

https://winterpokal.mtb-news.de/api/v1/<TYPE>/<METHOD>/<ARGUMENT>.json

Dabei bedeuten:

  • TYPE: Datentyp, z. B. entries für Einträge oder users für Benutzer
  • METHOD: Methode, die aufgerufen wird, z. B. add oder delete
  • ARGUMENT: Argument für die Methode, damit wird z. B. eine ID übergeben

Einige API-Funktionen bieten die Möglichkeit, mit weiteren Parameter die Ausgabe noch weiter zu manipulieren. Beispielsweise kann die Anzahl der gelieferten Einträge bei manchen Methoden eingeschränkt werden:

https://winterpokal.mtb-news.de/api/v1/<TYPE>/<METHOD>/<ARGUMENT>.json?<PARAM1>=<VALUE1>&<PARAM2>=<VALUE2>

Parameter-Namen und -Werte werden als normale GET-Parameter übergeben.

Clone this wiki locally