API (JSON-RPC)

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.

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 Verfü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 → Add-ons → 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 angehängt:

1

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.

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
    "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:

1
2
3
4

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:

1
2
3
4
5
6
7
8
9

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

Attribut 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.
Für benutzerdefinierte Kategorien bzw. Attribute finden Sie die technischen Schlüssel in der jeweiliges benutzerdefinierten Kategorie. Dort ist es möglich die technisches Schlüssel neu zu benennen.

Endpunkt Dokumentation v2#

Hier finden Sie v2 API-Anfragen mit ihren Anfragetypen, Antworttypen, Argumenten und der Form des Anfrage.

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:

Dokumentation zum Download (veraltet)#

Eine von den Entwicklern erstellte Dokumentation steht im PDF-Format zum Download.

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

FAQ#

Error Messages#

Releases#