Home

API-Dokumentation

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

Es ist damit möglich, Daten aus der dem Fotoalbum auszulesen und neue Fotos hochzuladen.

Projekte welche die API-Funktionen nutzen

n/a

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

API-Funktionen

TODO

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: http://fotos.mtb-news.de/api-keys oder http://fotos.rennrad-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://fotos.mtb-news.de/api/v1/photos/user/257.json?limit=5

PHP-Beispielskript:

<?php
// initialize curl ressource handle
$c = curl_init('https://fotos.mtb-news.de/api/v1/photos/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: Das Fotoalbum auf rennrad-news.de bietet die selben API-Funktionen. In den URLs muss lediglich mtb-news.de durch rennrad-news.de ersetzt werden.

Info: Die API-Funktionen sind mit HTTP und HTTPS erreichbar. HTTPS ist zu bevorzugen.

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

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

https://fotos.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://fotos.mtb-news.de/api/v1/<TYPE>/<METHOD>/<ARGUMENT>.json?<PARAM1>=<VALUE1>&<PARAM2>=<VALUE2>

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