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 → Allgemeine Einstellungen
.
Info
Das Entfernen von HTML-Tags aus Beschreibungsfeldern ist erst ab i-doit Version 1.15.2 mit installierter API Version 1.11.3 möglich.
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. Mit dem API Key wird der Mandant identifiziert.
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.
Dies erhöht außerdem die Performance erheblich.
Der für API-Aktionen verwendete Standardbenutzer ist "Api System“. Dieser kann bei Bedarf unter "Kontakte -> Personen" gefunden werden.
Dieser wird nur verwendet wenn kein Benutzername/Passwort für die Verbindung zur API Schnittstelle verwendet wird.
Wird die Person archiviert/gelöscht kann die API nicht mehr ohne Authentifizierung genutzt werden.
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 finden Sie in der Verwaltung:
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 |
---|---|---|---|
Idoit.API.Client | https://github.com/OKT90/Idoit.API.Client | C# | 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)
Seit Version 1.8.1 wird die API als Add-on veröffentlicht. Vorherige Releases waren in i-doit inkludiert.
FAQ
Error Messages
Error Message | Problem |
---|---|
Usersettings are only available after logging in. (i-doit <= 21) | Die Api System Person wurde archiviert oder gelöscht. Lösung: Die Api System Person muss wiederhergestellt werden oder es muss eine Authentifizierungsmethode genutzt werden. |
i-doit system error: Could not connect tenant database. (i-doit >=22) | Die Api System Person wurde archiviert oder gelöscht. Lösung: Die Api System Person muss wiederhergestellt werden oder es muss eine Authentifizierungsmethode genutzt werden. |
Releases
Version | Datum | Changelog |
---|---|---|
1.13.1 | 24.01.2023 | [Bug] Some fields are not being validated [Bug] The Login method can use old session keys [Bug] Validation error f_popup_ [Bug] Setting a Dialog Attribute via causes Fatal error [Bug] Failed validation breaks the response [Bug] installDate is always set to actual date/time [Bug] The addresses attribute of the Network > Port category is incorrectly validated by API validation [Bug] Date of Change is not altered when archiving a object via API |
1.13 | 05.09.2022 | [Task] PHP 8.0 compatibility [Bug] Reports displayed via the API show language constants [Bug] The Hostname field of the Monitoring category is incorrectly validated by API validation [Bug] Changing the object type via the API via type: dialog constant is not possible [Bug] An EntryID is needed to purge single-value entries [Bug] The API shall be able to change passwords of users [Bug] The Host address field of the Network > Port category is incorrectly validated by API validation [Bug] The Latitude, Longitude and Position fields in the Location category cabinet are incorrectly validated by API validation [Bug] The Type and Assigned license key fields of the Software Assignment category are incorrectly validated by API validation [Bug] The Image attribute of the Object picture category is incorrectly validated by API validation |
1.12.3 | 21.02.2022 | [Bug] Edit host address > primary_fqdn sets field default gateway for the network to Yes [Bug] If you edit an entry in the host address category, the IP address is removed. |
1.12.2 | 09.08.2021 | [Improvement] New parameters "offset" and "limit" for the "cmdb.category.read" method [Bug] Virtual Switches > Creating Port Groups generates SQL error message [Bug] Cluster members cannot be assigned via API using the category C__CATG__CLUSTER_MEMBERSHIPS [Bug] The API can not create sub-categories in 'cmdb.object.create' context [Bug] Layer 3 nets cannot be assigned with API validation enabled in Layer 2 nets [Bug] When the layer 3 net is changed the layer 3 net is assigned to itself under layer 2 net assignment [Bug] The category SLA (C__CATG__SLA) cannot be described via the API / With API validation switched off the category is emptied [Bug] Dialog+ fields with 'PropertyFactory' definition can not be written |
1.12.1 | 18.01.2021 | [Bug] cmdb.category.quickpurge cannot be used with custom categories [Bug] API version 1.12 can no longer be used in the open variant of i-doit |
1.12 | 14.01.2021 | [Bug] API: It is not possible to create a volume license via the API if "type": "volume license" is used [Bug] Saving the "Layer-2 Nets" category deletes ip helper [Bug] Contact assignment of a group of people will be deleted if it is updated via the API |
1.11.3 | 01.12.2020 | [Bug] Assign cable with fibers/leads while saving connection [Bug] Limit assignment categories to one entry while creating [Bug] Do not connect root location while creating cluster membership [Bug] Do not create wrong output after removing cable connection [Bug] Cannot assign objects to category "locally assigned objects" (requires i-doit 1.15.1) [Bug] The category C__CATG__IMAGE is not read correctly via the API [Bug] The category C__CATG__IMAGE cannot be written correctly [Bug] The dates of the category contract information cannot be set via the API [Bug] Category > Assigned Subscriptions C__CATG__ASSIGNED_SUBSCRIPTIONS key uuid cannot be set via string only via int [Bug] Read Methods: Do not output HTML tags in description fields [Bug] Objects can only be created via the API if the right to all object types is granted [Bug] Ports cannot be uniquely referenced via the API [Bug] Empty string supplied via API |
1.11.2 | 24.06.2020 | [Bug] API method: cmdb.object overrides the rights system |
1.11.1 | 09.04.2020 | [Bug] Updates via the API (save method) sets arbitrary entries in the Virtual Host category |
1.11 | 23.03.2020 | [Bug] Do not connect root location while creating cluster membership |
1.10.4 | 02.09.2019 | [Improvement] Add RPC to handle the CMDB status |
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" |