i-doit API

Als IT-Dienstleister bieten wir nicht nur Web Services oder Schulungen, sondern unter anderem auch Hosting an. Im Hosting-Bereich ist eine umfassende und geordnete IT-Dokumentation zwingend erforderlich um ein reibungsloses Arbeiten zu ermöglichen.  Als Lösung wird eine sog. CMDB (Configuration Management Database) eingesetzt, welche nicht nur als eine Inventarisierungs-Datenbank dient, sondern auch die gegenseitigen Abhängigkeiten der Objekte verwaltet. I-doit ist eine solche CMDB.
Seit der i-doit Version 1.8 ist die API kein Bestandteil der Pro-Version mehr und wird als separates Modul ausgeliefert welches frei verfügbar ist. Infolge dessen hab ich ein Azubiprojekt bekommen bei dem man die Funktionsweise einer API kennenlernen kann. Ich zeige im ersten Teil der i-doit API Serie wie man einen Request  über den curl – Befehl versendet.

Hat man die API über die Web GUI von i-doit konfiguriert kann man über folgende URL, welche an die Basis-URL angehängt wird, zugreifen:

/src/jsonrpc.php

Die Programmierschnittstelle kann auf Daten der CMDB über das JSON-Format zugreifen, d.h. es werden JSON-RPC Requests per HTTP-Post an i-doit geschickt und als JSON-RPC Response (mit HTTP-Header application/json) zurückgegeben. Somit kann man entweder über den curl – Befehl oder über einen RESTClient (z.B. als Firefox-Addon) die API ansprechen.
Ein beispielhafter Aufbau eines Request könnte folgendermaßen aussehen :

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "cmdb.objects.read",
  "params": {
    "apikey": "random_key",
    "filter": {
      "type": "4"
    }
  }
}

• jsonrpc – version: Da i-doit ausschließlich die Version 2.0 des RPC-Request untersützt
• id: Ein optionaler skalarer Wert (True, False, String, Numer) welcher aber nicht Null sein darf. Lässt man diesen Parameter aus, so wird lediglich eine Mitteilung verschickt, sodass der Server keine Rückmeldung generiert
• method: Die zu aufrufende Methode
• params: Parameter welche an die Methode übergeben werden

curl -s --data '{"jsonrpc":"2.0","id":"1","method":"cmdb.objects.read","params": \
{"apikey":"random_key","filter":{"type":"4"}}}' \
--header "Content-Type: application/json" \
 | python -m json.tool

Mit diesem Request lesen wir alle Objekte in der CMDB aus welche dem Typ 4 (Rack) entsprechen:

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": [{
    "cmdb_status": "6",
    "cmdb_status_title": "in operation",
    "created": "2018-01-05 11:32:13",
    "id": "33",
    "image": "https://example-idoit-web-gui.de/images/objecttypes/something.png",
    "status": "2",
    "sysid": "SYSID_[RANDOMNUMBER_3849274329]",
    "title": "RacknameXYZ",
    "type": "4",
    "type_group_title": "Infrastructure",
    "type_title": "Rack",
    "updated": "2018-01-11 13:38:09"
  },
  {
    ...
    ...
  }]
}

Um z.B. alle Informationen einer Kategorie eines Objektes auslesen zu können, benutzt man die Methode cmdb.category.read:

curl -s --data '{"jsonrpc":"2.0","id":"1","method":"cmdb.category.read","params": \
{"apikey":"random_key","objID":"1234","category":"C__CATG__MODEL"}' \
--header "Content-Type: application/json" \
 | python -m json.tool

Response:

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": [{
    "description": "",
    "firmware": "",
    "id": "307",
    "manufacturer": {
      "const": null,
      "id": "5",
      "title": "Random_Manufacturer_Name",
      "title_lang": "Random_Manufacturer_Name"
    },
  "objID": "Uniqe-Object-ID",
  "productid": "",
  "serial": "1235265477457",
  "service_tag": "",
  "title": {
    "const": null,
    "id": "71",
    "title": "XYZ1234",
    "title_lang": "XYZ1234"
  }
  }]
}

Eine ausführliche Liste aller in i-doit benutzten Kategorien kann man unter folgendem URL-Anhang aufrufen:

Darüber hinaus kann man über die i-doit API nicht nur Daten aus einer CMDB herauslesen, sondern auch erstellen, aktualisieren oder löschen. Diese Methoden werde ich im Teil 2 dieser Serie abhandeln.
 
Quellen: i-doit Knowledge Base