API (JSON-RPC): Schnelleinstieg

Die i-doit API ermöglicht die programmatische Verwaltung der CMDB über JSON-RPC 2.0. Objekte können erstellt, gelesen, aktualisiert und gelöscht werden.

Wichtig: Niemals direkt per SQL auf die Datenbank zugreifen — das umgeht interne Mechanismen und kann Datenintegrität, Beziehungen und Logbuch-Einträge beschädigen.

Voraussetzungen

• API Add-on installiert (kostenlos im Kundenportal verfügbar, aktuelle Version: 2.5)
• API-Key konfiguriert unter Verwaltung > Add-ons > JSON-RPC API

Endpunkt

https://<ihr-i-doit>/src/jsonrpc.php

Alle Anfragen werden als HTTP POST mit JSON-Body gesendet.

Authentifizierung

Jede Anfrage benötigt mindestens den API-Key (identifiziert den Mandanten). Optional können Benutzerdaten für die Rechteverwaltung und Nachvollziehbarkeit im Logbuch mitgegeben werden.

Praxisbeispiele

Objekt erstellen

{
    "jsonrpc": "2.0",
    "method": "cmdb.object.create",
    "params": {
        "type": "C__OBJTYPE__SERVER",
        "title": "SRV-WEB-001",
        "apikey": "ihr-api-key"
    },
    "id": 1
}

Objekt lesen

{
    "jsonrpc": "2.0",
    "method": "cmdb.object.read",
    "params": {
        "id": 1000,
        "apikey": "ihr-api-key"
    },
    "id": 2
}

Kategorie-Daten schreiben (z.B. Modell)

{
    "jsonrpc": "2.0",
    "method": "cmdb.category.create",
    "params": {
        "objID": 1000,
        "data": {
            "manufacturer": "Dell",
            "title": "PowerEdge R740"
        },
        "category": "C__CATG__MODEL",
        "apikey": "ihr-api-key"
    },
    "id": 3
}

Objekt löschen (3 Stufen)

// Archivieren
{"method": "cmdb.object.delete", "params": {"id": 1000, "status": "C__RECORD_STATUS__ARCHIVED", "apikey": "xxx"}}

// Löschen
{"method": "cmdb.object.delete", "params": {"id": 1000, "status": "C__RECORD_STATUS__DELETED", "apikey": "xxx"}}

// Endgültig entfernen (Purge)
{"method": "cmdb.object.purge", "params": {"object": 1000, "apikey": "xxx"}}

Suche

{
    "jsonrpc": "2.0",
    "method": "idoit.search",
    "params": {
        "q": "SRV-WEB",
        "apikey": "ihr-api-key"
    },
    "id": 4
}

Wichtige Konstanten finden

Performance-Tipps

• Batch-Requests: Mehrere Anfragen in einem HTTP-Request bündeln — reduziert Netzwerk-Overhead
• Session-Management: Bei vielen Anfragen idoit.login / idoit.logout verwenden statt bei jeder Anfrage neu zu authentifizieren
• Logging: API-Aufrufe werden unter /log/ protokolliert — bei hohem Volumen Speicherplatz beobachten

Fehlercodes

Community-Bibliotheken

Es gibt inoffizielle Client-Libraries für PHP, Python, Go, C#, JavaScript, PowerShell und Ansible. Eine Übersicht findet sich in der Knowledge Base.

Ausführliche Dokumentation: API-Referenz | API-Beispiele | Tipps & Tricks