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).
| Methode | Beschreibung |
|---|---|
idoit.version | Version von i-doit abfragen |
idoit.login | Login |
idoit.logout | Logout |
idoit.constants | Konstanten abfragen |
idoit.search | In i-doit suchen |
cmdb.objects | Objekte auslesen |
cmdb.object.{create, read, update, delete} | Ein Objekt erstellen, auslesen, aktualisieren, archivieren/als gelöscht markieren/unwiderruflich löschen |
cmdb.object_types | Objekttypen abfragen |
cmdb.category_info | Attribute 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.reports | Einen Report ausführen |
cmdb.objects_by_relation | Objekte nach Beziehungsart auslesen |
cmdb.location_tree | Standort-Pfad auslesen |
cmdb.workstation_components | Arbeitsplatzkomponenten auslesen |
cmdb.object_type_categories | Auslesen, welche Kategorien zu welchen Objekttypen konfiguriert sind |
cmdb.object_type_groups | Auslesen, welche Objekttypen welchen Objekttypgruppen zugeordnet sind |
cmdb.logbook.{create, read} | Einen Logbuch-Eintrag erstellen, auslesen |
cmdb.impact | Rekursive 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:
| Name | Website | Programmiersprache | Lizenz |
|---|---|---|---|
| https://bitbucket.org/dstuecken/i-doit-api-clients/src/6144694a6654b19254b13a7a652659eaf11e9f62/php/?at=master | PHP | MIT |
idoit-api-client | https://bitbucket.org/dstuecken/i-doit-api-clients/src/6144694a6654b19254b13a7a652659eaf11e9f62/java/?at=master | Java | MIT |
i-doit API client | https://github.com/bheisig/i-doit-api-client-php | PHP | AGPLv3 |
| i-doit CLI | https://github.com/bheisig/i-doit-cli | PHP | AGPLv3 |
| i-doit-go-api | https://github.com/cseeger-epages/i-doit-go-api | Go | GPLv3 |
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
| Version | Datum | Changelog |
|---|---|---|
| 1.10.3 | 06.05.2019 | [Bug] Assignment of devices to segments in slots not possible |
| 1.10.2 | 01.04.2019 | [Bug] cmdb.category.read: Lese nur Einträge mit Status "normal", wenn nicht anders angegeben |
| 1.10.1 | 23.01.2019 | [Bug] Authentifizierung mit LDAP nicht möglich |
| 1.10 | 17.12.2018 | [Verbesserung] Validierung von API Requests per Experteneinstellung aktivieren |
| 1.9.1 | 16.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.9 | 23.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.1 | 02.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.