Was kann man mit der Foreman REST API eigentlich alles machen?

API steht für: application programming interface. Die API einer Anwendung enthält definierte Url’s für ausführbare Funktionen, wie z.B. das Auslesen von Konfigurationseinstellungen oder auch das Anlegen von neuen Daten.

Bei der Verwendung der REST API werden Aufrufe von Web Adressen durchgeführt mit einem oder mehreren entsprechenden Parametern. Sind der Aufruf und die Parameter gültig, werden die angeforderten Informationen oder ein Status vom Zielserver zurückgegeben. Beispielsweise lassen sich alle angelegten Environments im Foreman über folgenden Aufruf (GET Request) auslesen:

https://mein-foreman-server.de/api/environments

Die Informationen vom Foreman Server über die Environments werden dann im JSON Format ausgegeben:

{
  "total": 34,
  "subtotal": 34,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results": [{"created_at":"2015-10-07T07:21:42Z","updated_at":"2015-10-07T07:21:42Z","name":"api_new","id":3},{"created_at":"2015-10-07T07:21:17Z","updated_at":"2015-10-07T07:21:17Z","name":"apitest","id":2}, ...]
}

Wie man sieht, ist das Auslesen von Informationen mit Hilfe der REST API recht einfach.

Schwieriger wird es bei komplexeren Aufgaben in Verbindung mit bestehenden Daten, die in Abhängigkeit stehen. Beispielsweise wenn man mehrere Daten für bereits angelegte Organisationen oder Locations im Foreman einspielen möchte. In diesem Fall muss man etwas aufwändiger einen Import generieren. Hier kommen dann Nachfolgende REST API Optionen ins Spiel, um den Import oder die Anpassungen automatisiert durchführen zu können.

• Mit der Bash-Shell über den CURL Befehl
• Mit dem Foreman-API Gem
• direkt mit einer Programmiersprache

Die REST API Zugriffe auf den Foreman 1.9. haben wir folgendermaßen getestet.

1. Mit CURL über die Bash-Konsole
2. Mit Ruby in den Versionen 1.8.7, 1.9.2 und 2.2.0 und den Bibliotheken net/http(s) und uri
3. Mit Ruby On Rails 4 und dem Gem ActiveResource

Unser Fazit aus den Tests mit der Forman REST API.

Hat man vor die REST API kurz zu testen oder ein paar kleinere Anpassungen per Skript durchzuführen, ist die Verwendung von CURL die wohl einfachste und schnellste Option.

Das Beispiel von oben mit CURL umgesetzt, sieht wie folgt aus.

$ curl -u admin:password -H "Accept:application/json" https://mein-foreman-server.de/api/environments

Möchte man komplexere Importe, Updates oder andere Bereinigungen vornehmen, ist die Verwendung einer Programmiersprache sehr empfehlenswert. In unseren Beispielen konnten wir mit Ruby und dem Gem ActiveResource gut arbeiten und schnell eine leicht verständliche und wiederverwertbare Schnittstelle erstellen.

Ist aber der Einsatz vom Gem ActiveResource oder die Installation auf einem Server nicht möglich, kann man auch mit der auf dem Server vorhandenen Ruby Version schnell ein Programm/Skript erstellen, dass die gewünschten Aufgaben erledigt. Alternativ gäbe es auch noch ein Gem von den Foreman Entwicklern mit dem Namen Foreman API.

Was kann man mit der Foreman REST API eigentlich alles machen? – Eine ganze Menge!