Die Verwaltung von lima-city führt ein Doppelleben: sie ist gleichzeitig auch eine API. Die Funktionen der Verwaltung lassen sich mit Hilfe eines API-Keys auch programmatisch erledigen. Die API ist REST-basiert und benutzt API-Keys im HTTP-Authorization-Header für die Authentifizierung.
Unsere Verwaltungsoberfläche bauen wir seit einiger Zeit Schritt für Schritt zu einem reinen API-Konsumenten um. Das Ziel ist es, dass alles, was über die Verwaltung möglich ist, auch per API erledigt werden kann. Derzeit geben deshalb einige Endpoints kein JSON sondern HTML zurück. Bitte gib uns Bescheid, wenn ein Endpunkt nur HTML zurückliefert.
Eine Übersicht der REST-API kannst Du im OpenAPI Viewer einsehen:
Praktisch jede Funktion der Verwaltung lässt sich statt mit einem Browser auch per API-Key durchführen. Dazu muss statt einer Browser-Session, welche den Account identifiziert, ein API-Key übergeben werden. Bitte verwende das Menü "API-Keys" in der Verwaltung, um die API-Keys zu verwalten. Der API-Key wird als "Passwort"-Feld für die HTTP-Authorization übermittelt, sofern als Username "api" angegeben wird:
<?php
$verb = 'GET';
$secret_api_key = "FNtmIpQNDDipCWi83WsHggxHYCswSQnA";
$process = curl_init("https://www.lima-city.de/usercp/php_error_log.json");
curl_setopt($process, CURLOPT_USERPWD, "api:" . $secret_api_key);
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($process, CURLOPT_HTTPHEADER, array ('content-type: application/json'));
$response_body = curl_exec($process);
$http_code = curl_getinfo($process, CURLINFO_HTTP_CODE);
if($http_code >= 300) {
trigger_error("Unexpected API response code: ${http_code}: ${response_body}", E_USER_ERROR);
die();
}
curl_close($process);
Ein weiteres Beispiel, das Daten sendet:
<?php
$verb = 'POST';
$secret_api_key = "FNtmIpQNDDipCWi83WsHggxHYCswSQnA";
$payload = array('php_version' => array('version' => '7.0'));
$process = curl_init("https://www.lima-city.de/usercp/php_version.json");
curl_setopt($process, CURLOPT_USERPWD, "api:" . $secret_api_key);
curl_setopt($process, CURLOPT_CUSTOMREQUEST, $verb);
curl_setopt($process, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($process, CURLOPT_HTTPHEADER, array ('content-type: application/json'));
$response_body = curl_exec($process);
$http_code = curl_getinfo($process, CURLINFO_HTTP_CODE);
if($http_code >= 300) {
trigger_error("Unexpected API response code: ${http_code}: ${response_body}", E_USER_ERROR);
die();
}
curl_close($process);
Die API-Berechtigungen basieren auf einem Rollen-Konzept. Ein API-Key hat eine oder mehrere Rollen, welche den Zugriff auf Ressourcen regeln. Es gibt im Normalfall je Ressource drei Rollen, Reader (nur lesen), Editor (lesen und bearbeiten, jedoch nicht erstellen und löschen) sowie Admin (alle Rechte). Ressourcen meint Ressourcen im Sinne der REST-Spezifikation. Ein simples Beispiel für Rollen:
# Rollen, welche Zugriff auf FTP-Accounts gewähren
ftp_accounts.reader
ftp_accounts.editor
ftp_accounts.admin
# Drei Rollen, welche Zugriff auf Cloud-VPS haben
cloud_vps.reader
cloud_vps.editor
cloud_vps.admin
Ein API-Key, dem wir nun beispielsweise die Rollen "cloud_vps.reader" und "ftp_accounts.reader" zuweisen hat dementsprechend Lesezugriff auf Cloud-VPS und FTP-Accounts, kann jedoch keine solchen erstellen, ändern oder löschen.