Inhaltsverzeichnis



i-doit ermöglicht den externen Zugriff auf die IT-Dokumentation über eine Programmierschnittstelle, auch API genannt. Es können Daten gelesen, erstellt, aktualisiert und auch gelöscht werden. Somit stellt die API ähnliche Funktionen wie die Web GUI bereit – nur lassen sich diese problemlos automatisieren.

Technischer Hintergrund

Die API von i-doit bringt typische CRUD-Funktionalitäten mit. Daten können darüber

  • erstellt (Create),
  • gelesen (Read),
  • aktualisiert (Update) und
  • gelöscht (Delete) werden.

Ein Client (beispielsweise in Form eines Scripts) sendet dazu einen Request an den Server (i-doit), um eine Methode auf dem Server ausführen zu lasen. Diese Vorgehensweise nennt man Remote Procedure Call (RPC). Das Ergebnis der Methode wird an den Client als Antwort (Response) zurückgegeben. Die API von i-doit stützt sich bei dieser Kommunikation auf das Protokoll JSON-RPC in Version 2.0. Es verwendet als höheres Protokoll HTTP und als Austauschformat JavaScript Objekt Notation (JSON). Per HTTP POST wird ein Request im JSON-Format an den Server geschickt. Die Response erfolgt ebenfalls im JSON-Format.

API-Aufrufe können asynchron erfolgen, ohne den Zusammenhang zwischen Requests und Responses zu verlieren. Die verwendete Programmiersprache kann frei gewählt werden.

API statt Datenbank

Es ist sehr zu empfehlen, die API immer Datenbank-Manipulationen vorzuziehen. SQL Statements umgehen allerlei interne Verarbeitungsschritte. Wird per INSERT, UPDATE oder DELETE ein Datensatz via SQL manipuliert, könnte das die Datenintegrität gefährden und i-doit unbrauchbar machen.

Download

Die API wird für die pro-Variante als kostenloses Add-on im Kundenportal zum Download angeboten. Benutzern der open-Variante steht es ebenfalls kostenlos über die Website i-doit.org zur Vergfügung. Die Installation folgt demselben Prinzip der anderen Add-ons für i-doit.

Konfiguration

Die Konfiguration der API geschieht über die Web GUI von i-doit, zu finden unter Verwaltung → Schnittstellen / externe Daten → JSON-RPC API.

Zu beachten ist, dass das Logging von API Requests bei jedem Request eine Datei im Installationsverzeichnis von i-doit unter log/ anlegt. Dies könnte bei massivem Gebrauch der API zu einem erhöhten Speicherplatzbedarf führen.

Zugriff

Um die API von i-doit anzusprechen, gibt es eine spezielle URL. Der Basis-URL wird ein src/jsonrpc.php angehangen:

https://demo.i-doit.com/src/jsonrpc.php

Authentifizierung und Autorisierung

Damit Requests von der API verarbeitet werden, ist ein API Key erforderlich. Zudem kann aktiviert werden, dass ein dedizierter Benutzer-Account für die Anmeldung verwendet wird. Für diesen können wie gewohnt Rechte vergeben werden. Andernfalls stehen über die API alle Rechte zur Verfügung. Zusätzlicher Vorteil ist, dass man pro Dritt-System/Script einen dedizierten Benutzer angeben kann, um einfach nachvollziehen zu können, welche Datenflüsse von wo nach wo stattfinden.

Werden sehr viele Requests von einem Client aus gesendet (wir sprechen hier von tausenden), lohnt es sich, die API-Methode idoit.login zu nutzen, um sich lediglich einmal zu authentifizieren. Andernfalls kann es passieren, dass in zu kurzer Zeit zu viele Sessions erstellt, aber nicht wieder beendet werden. Dies könnte dazu führen, dass i-doit unbenutzbar wird, bis die Sessions beendet wurden.

Methoden

Eine ausführliche Dokumentation mit vielen Beispielen steht im PDF-Format zum Download zur Verfügung (siehe unten).

MethodeBeschreibung
idoit.versionVersion von i-doit abfragen
idoit.loginLogin
idoit.logoutLogout
idoit.constantsKonstanten abfragen
idoit.searchIn i-doit suchen
cmdb.objectsObjekte auslesen
cmdb.object.{create, read, update, delete}Ein Objekt erstellen, auslesen, aktualisieren, archivieren/als gelöscht markieren/unwiderruflich löschen
cmdb.object_typesObjekttypen abfragen
cmdb.category_infoAttribute zu einer Kategorie auslesen
cmdb.category.{create, read, update, delete}Einen Kategorie-Eintrag erstellen, lesen, aktualisieren, löschen
cmdb.dialog.{create, read}
Werte eines Dialog-Feldes erstellen oder auslesen
cmdb.reportsEinen Report ausführen
cmdb.objects_by_relationObjekte nach Beziehungsart auslesen
cmdb.location_treeStandort-Pfad auslesen
cmdb.workstation_componentsArbeitsplatzkomponenten auslesen
cmdb.object_type_categoriesAuslesen, welche Kategorien zu welchen Objekttypen konfiguriert sind
cmdb.object_type_groupsAuslesen, welche Objekttypen welchen Objekttypgruppen zugeordnet sind
cmdb.logbook.{create, read}Einen Logbuch-Eintrag erstellen, auslesen
cmdb.impactRekursive Abfrage aller Objektbeziehungen

Beispiel

Anhand eines simplen Beispiels wird ein neues Objekt vom Typ Server mit dem Objekt-Titel "My little server" über die API erstellt.

Request an den Server:

{
    "jsonrpc": "2.0",
    "method": "cmdb.object.create",
    "params": {
        "type": "C__OBJTYPE__SERVER",
        "title": "My little server",
        "apikey": "c1ia5q"
    },
    "id": 1
}

Diesen Request kann man für Testzwecke via cURL absenden:

curl \
--data '{"jsonrpc":"2.0","method":"cmdb.object.create","params":{"type":"C__OBJTYPE__SERVER","title":"My little server","apikey":"c1ia5q"},"id":1}' \
--header "Content-Type: application/json" \
https://demo.i-doit.com/src/jsonrpc.php

Die Response vom Server:

{
    "jsonrpc": "2.0",
    "result": {
        "id": "3351",
        "message": "Object was successfully created",
        "success": true
    },
    "id": 1
}

Kategorien in der IT-Dokumentation

Eine hilfreiche Auflistung aller in i-doit verwendeten Kategorien und Attribute liefert eine spezielle URL:

https://demo.i-doit.com/index.php?load=api_properties

Dort wird beispielsweise aufgelistet, unter welchem Namen Kategorien und Attribute angesprochen werden können und welche Datentypen die jeweiligen Attribute erwarten.

Clients und Libraries

Es gibt bereits zahlreiche Projekte und Produkte, die die API von i-doit benutzen. Einige Clients und Libraries stellen wir an dieser Stelle vor:

Feedback

Sollte ein Client oder eine Library in diesem Artikel noch nicht aufgeführt sein, freuen wir uns über eine kurze Nachricht an feedback@i-doit.com.

Dokumentation zum Download

Eine von den Entwicklern gepflegte Dokumentation steht im PDF-Format zum Download. (veraltet)

Releases

VersionDatumChangelog
1.10.306.05.2019
[Bug] Assignment of devices to segments in slots not possible

[Bug] Validating requests breaks altering attributes
1.10.201.04.2019
[Bug] cmdb.category.read: Lese nur Einträge mit Status "normal", wenn nicht anders angegeben

[Bug] Selektiere Wert in einem "Dialog+"-Attribut über dessen Konstante

[Bug] Korrigiere SQL-Fehler beim verbinden von 2 Anschlüssen

[Bug] Objekt löschen unter Angabe des Status (C__RECORD_STATUS__DELETED) führt zur Endlosschleife

[Bug] Objekt-Status muss beim Löschen zwingend angegeben werden, obwohl er optional sein sollte

[Bug] idoit.license.read: Gebe neues Format aus

[Bug] idoit.addons.read: Verwende neue Lizenzform

[Bug] Löschen einer unbekannten Datensatz ID gibt Erfolg aus

[Bug] Erstelle Objekte mit definierter SYSID über die API

[Bug] API gibt nicht alle IP-Adressen der IP-Liste zurück

[Bug] Lese Daten aus der Kategorie Laufwerk

[Bug] Personengruppen zuweisungen via API purgen

[Bug] Rückgabe des Attributs "Anrede" wiederherstellen
1.10.123.01.2019
[Bug] Authentifizierung mit LDAP nicht möglich
[Bug] SQL Injection Lücke bei Login
1.1017.12.2018
[Verbesserung] Validierung von API Requests per Experteneinstellung aktivieren
[Verbesserung] Unterschiedliche API keys sind in einem Batch Request nicht erlaubt
[Verbesserung] Fehler wird geworfen, wenn eine ID innerhalb eines Batch Request wiederholt wird
[Verbesserung] API Key verpflichtend, User-Login mit inkludiertem Rechtesystem optional
[Verbesserung] cmdb.category.save erstellt oder aktualisiert Kategorie-Einträge
[Verbesserung] Auslesen von Lizenzinformationen per API
[Verbesserung] Internes Logging menschen-lesbar machen
[Verbesserung] Filtern von Kategorie-Einträgen nach Status
[Verbesserung] Kategorie-Eintrag wiederherstellen
[Verbesserung] Kategorie-Eintrag bereinigen
[Verbesserung] Kategorie-Eintrag löschen
[Verbesserung] Kategorie-Eintrag archivieren
[Verbesserung] Objekt als Massenänderungsvorlage markieren
[Verbesserung] Objekt als Template markieren
[Verbesserung] Objekt wiederherstellen
[Verbesserung] Objekt bereinigen
[Verbesserung] Objekt löschen
[Verbesserung] Objekt archivieren
[Verbesserung] Erstelle Objekt mit Kategorie-Einträgen
[Verbesserung] Lese Objekte mit Kategorie-Einträgen
[Verbesserung] Gebe Integer-Wert bei einer Response nicht weiterhin als String zurück
[Verbesserung] Beschreibe in der Web GUI den Umgang mit Kategorien und Attributen
[Verbesserung] Console Commands via API aufrufen
[Verbesserung] Abfrage von Informationen installierter Add-ons
[Verbesserung] Auslesen aller Konstanten
[Verbesserung] Templates und Änderungsvorlagen auslesen, erstellen, aktualisieren und löschen
[Änderung] cmdb.category.create und .update sind veraltet
[Bug] cmdb.category.create: Lizenz-Schlüssel kann in Kategorie "Softwarezuweisung" nicht angegeben werden
[Bug] Rückwärtige Kategorien liefern keine oder falsche Verbindungen zu Objekten
[Bug] cmdb.category.read: Falsche Objektbeziehungen und Mehrfacheinträge in Kategorie "C__CATS_NET_TYPE__IPV4"
[Bug] API liefert bei Attribut "zone" der Kategorie "Hostadresse" bei leerer Zuweisung ein leeresArray, bei einem Eintrag stattdessen ein Objekt
[Bug] Unbekannte Attribute werden ignoriert
[Bug] Ungültige Werte führen nicht zu Fehlermeldung
[Bug] Server sendet keine Notifcation, wenn "id" im Request nicht gesetzt ist
[Bug] cmdb.category.read liefert Einträge für leere Kategorien
[Bug] Inkorrekte Fehlermeldung bei der Verknüpfung eines Nicht-Netz-Objekts über die API in einem Feld, in dem ein Netz-Objekt erwartet wird (Hostadresse)
[Bug] Kabel bleiben unbenutzt wenn Verbindungen mittels der API erstellt werden
[Bug] Application-Priority wird nicht übernommen
[Bug] Timeout wird nicht nach jedem Request zurückgesetzt
[Bug] Fehler in Verbindung mit Hersteller/Modell über die API
[Bug] API: Faserverbindungen können nicht ausgelesen werden
[Bug] Übergibt man eine ID als String ist es möglich das die falsche Daten übernommen werden
[Bug] Ports verbinden über die API nutzt falsche Objekte als Kabel
1.9.116.04.2018
[Bug]           cmdb.reports.read wirft SQL-Fehler bei variablen Reports
[Bug]           Methode cmdb.reports wirft PHP Warning
[Bug]           Nach Erstellung eines Objekts muss ein Reindex ausgeführt werden, um das Objekt per Suche zu finden
[Bug]           Kategorie-Eintrag für C__CATS__ORGANIZATION_CONTACT_ASSIGNMENT kann nicht erstellt werden
[Bug]           API berücksichtigt Sprachen-Parameter nicht
1.923.01.2018
[Verbesserung]  Suche nach Objekten anhand von Attributen und Werten
[Verbesserung]  Benutzerrechte bei API Calls berücksichtigen
[Verbesserung]  Angabe eines Templates beim Erstellen eines Objekts via "cmdb.object.create"
[Bug]           Datei kann nicht hochgeladen werden
[Bug]           Über die API geänderter Wert erzeugt Logbucheintrag ohne Titel
[Bug]           Benutzerdefinierte Dialog Plus Inhalte über die API auslesen
[Bug]           Auslesen von Passwörtern nicht möglich
[Bug]           Methode "cmdb.object.create" legt ObjektID's teils als String, teils als Integer an
[Bug]           Datenbank-Fehler statt Meldung im Klartext beim Versuch, ein Objekt, das nicht existiert, über die API zu löschen
[Bug]           Dialog Plus Felder, die eine Abhängigkeit zu einem anderen Attribut haben, werden nicht angelegt
1.8.102.03.2017
[Bug]           Nach Erstellen werden benutzerdefinierte Dialog+-Felder nicht angezeigt
[Bug]           Angelegte Dialog-Einträge erhalten den Status 1 anstelle von 2 (Normal)
[Bug]           cmdb.object.delete berücksichtigt Parameter "status" nicht
[Bug]           cmdb.category.create wirft Datenbank-Fehler für Kategorie "Modell"

Seit Version 1.8.1 wird die API als Add-on veröffentlicht. Vorherige Releases waren in i-doit inkludiert.