REST-API verstehen - Docusnap365

Die REST-API stellt den Bestand aus Docusnap365 für eigene Anwendungen bereit: Assets lesen, abfragen und anlegen. Sie ist der Weg für alles, was regelmäßig und maschinell geschieht – Auswertungen im eigenen Werkzeug, Übernahme in ein anderes System, eigene Oberflächen auf den eigenen Daten. Sie liefert dieselben Daten wie die Oberfläche unter denselben Rechten. Für Fragen in eigenen Worten dient der KI-Assistent, für die Anbindung eines KI-Tools der MCP-Connector. Die REST-API ist der programmatische Weg.

Adresse und Aufrufe

Alle Aufrufe liegen unter https://api.docusnap365.com/api/v1. Die API arbeitet ausschließlich mit Assets und kennt sieben Endpunkte:

Aufgabe	Endpunkt	Zugriff
Assets auflisten	`GET /assets`	Lesen
Ein Asset lesen	`GET /asset/{id}`	Lesen
Assets abfragen, mit Details	`POST /assets/query`	Lesen
Details eines Assets laden	`POST /assets/expand`	Lesen
Weiterblättern	`POST /cursor/continue`	Lesen
Asset anlegen oder aktualisieren	`POST /asset`	Lesen und Schreiben
Mehrere Assets anlegen oder aktualisieren	`POST /asset/bulk`	Lesen und Schreiben

Parameter, Schemas und Beispiele jedes Endpunkts stehen in der API-Referenz in der Seitenleiste.

curl https://api.docusnap365.com/api/v1/assets \
  -H "x-api-key: <Ihr Schlüssel>"

Die Antwort ist eine Seite mit höchstens 50 Assets.

Schlüssel und Rechte

Jeder Aufruf trägt einen API-Schlüssel in der Kopfzeile x-api-key. Weitere Kopfzeilen und eine vorherige Anmeldung sind nicht nötig. Schlüssel legen Besitzer und Administratoren unter Verwaltung › Integrationen › API-Schlüssel an; wie das geht, steht unter API-Schlüssel verwalten. Beim Anlegen wählen Sie den Zugriff. Lesen genügt für die lesenden Endpunkte, POST /asset und POST /asset/bulk verlangen Lesen und Schreiben. Ein Schlüssel ohne den nötigen Zugriff erhält die Antwort 403. Fehlt der Schlüssel oder ist er ungültig, antwortet die API mit 401 ohne Inhalt. Ein Schlüssel gehört einem Benutzer, und dessen Rechte gelten: Was dieser Benutzer in der Oberfläche nicht sieht, liefert die API auch nicht. Fehlende Rechte erzeugen keinen Fehler, sondern eine kleinere Ergebnismenge. Wer weniger sieht als erwartet, prüft zuerst die Rechte des Benutzers, dann die Abfrage. Ein Asset, das der Benutzer nicht sieht, verhält sich wie ein nicht vorhandenes: GET /asset/{id} und POST /assets/expand antworten mit 404.

Assets und Typen

Ein Asset besteht aus seinen Stammangaben und, auf Wunsch, aus seinen Details. Die Stammangaben liefert jeder lesende Endpunkt: unter anderem id, name, schemaId, objectType, parentId, die Zuordnung zu Organisation, Standort, Plattform und Domäne sowie status, Herkunft und die Angaben zu Anlegen und Ändern. Alles Weitere steht nicht in den Stammangaben, sondern kommt über Expands. Jedes Asset hat einen Typ, in der API schemaId. Der Typ bestimmt, welche Daten das Asset trägt. Die Typen mit ihren Feldern stehen im Datenmodell. Zum Anlegen eines Assets benötigen Sie die schemaId des passenden Typs.

Lesen und Abfragen

GET /assets liefert die ersten 50 Assets. select und search übergeben Sie als JSON-Array:

GET /api/v1/assets?select=["id","name","status"]&search=["name=SRV"]

search nimmt Einträge der Form feld=wert und findet, was den Wert enthält, ohne Beachtung der Groß- und Kleinschreibung. Mehrere Einträge gelten zusammen. select bestimmt auf diesem Endpunkt nur, welche Felder gelesen werden; die Antwort trägt trotzdem alle Felder, nicht gewählte mit leerem Wert. POST /assets/query ist der Weg für Filter, Sortierung und Feldauswahl. Alle Teile der Abfrage sind wahlweise:

Teil	Bedeutung
`select`	Stammangaben, die zurückkommen; ohne Angabe alle
`filter`	Gruppe aus Bedingungen mit `path`, `op` und `value`, verknüpft mit `And` oder `Or`; Gruppen lassen sich über `groups` schachteln
`sort`	Felder mit Richtung (`desc`); `nulls` bestimmt die Stellung leerer Werte
`limit`	Assets je Seite, Vorgabe 50
`expands`	Details, die mitkommen

{
  "select": ["id", "name", "schemaId"],
  "filter": {
    "logic": "And",
    "conditions": [
      { "path": "objectType", "op": "Eq", "value": "basedef::windows" },
      { "path": "name", "op": "StartsWith", "value": "SRV" }
    ]
  },
  "sort": [{ "path": "name", "desc": false }],
  "limit": 50
}

Gefiltert und sortiert wird nur auf den Stammangaben. Ein Pfad mit data. im Filter der Abfrage endet mit 400 UNKNOWN_PATH. Die erfassten Daten eines Typs lesen Sie über ein Expand und werten sie in der eigenen Anwendung aus.

Gruppe	Operatoren	Hinweis
Vergleich	`Eq`, `Neq`, `Gt`, `Gte`, `Lt`, `Lte`	`Neq` behält Assets mit leerem Feld
Text	`Contains`, `StartsWith`, `EndsWith`	ohne Beachtung der Groß- und Kleinschreibung
Muster	`Like`	mit `%` und `_`, Groß- und Kleinschreibung zählen
Menge	`In`, `NotIn`	`value` ist ein Array; `NotIn` behält Assets mit leerem Feld
Leer	`IsNull`, `IsNotNull`	ohne `value`
Liste	`ArrayAny`, `ArrayAll`, `ArrayContains`	für Listen in den Daten eines Expands; `ArrayAll` verlangt wie `ArrayAny` nur ein passendes Element

Details laden

Ein Expand lädt zu jedem Asset einen Teil seiner Details. Es gibt vier mit festen Namen:

Name	Je Asset	Inhalt
`object_data`	ein Eintrag	die erfassten Daten des Typs, zum Beispiel Seriennummer, Hersteller, Betriebssystem
`object_essentials`	mehrere	die Kurzansicht, ein Eintrag je Art (`quickinfo`, `statistics`)
`object_blocks`	mehrere	die Blöcke des Assets, je Eintrag ein `type` mit seinen Daten
`children`	mehrere	die untergeordneten Assets mit denselben Stammangaben

Ein Expand hat eigene select, filter, sort und limit (Vorgabe 50). select wählt auch einzelne Werte der Daten, etwa data.serialNumber. Welche Werte ein Typ hat, steht im Datenmodell. Ein Filter auf schemaId in der Abfrage beschleunigt die Auflösung der data.-Pfade. filter, sort und limit wirken je Asset bei object_essentials, object_blocks und children; bei object_data wirkt nur select.

object_blocks ist der aufwendige Fall: Ein Asset trägt im Mittel mehrere tausend Blöcke, im Einzelfall über 95.000. Fordern Sie dieses Expand nur mit filter und einem kleinen limit an.

Ein unbekannter Name in expands wird in POST /assets/query übergangen und von POST /assets/expand mit 400 abgewiesen. Wo die Details in der Antwort stehen, hängt vom select ab. Mit select steht jedes Expand unter seinem Namen direkt am Asset, object_data als Objekt, die übrigen als Liste. Ohne select stehen alle Expands gesammelt unter expands, jedes als Liste. POST /assets/expand lädt ein Expand für ein einzelnes Asset. Pflicht sind parentId und expandName. Mit einem cursor aus incompleteExpands oder nextCursor setzt der Aufruf an der Stelle fort, an der der Cursor ausgestellt wurde; select, filter, sort und limit im Körper gelten dann nicht.

Weiterblättern mit dem Cursor

Jede lesende Antwort außer GET /asset/{id} hat dieselbe Form:

Feld	Inhalt
`items`	die Assets dieser Seite
`hasMore`	ob weitere Seiten folgen
`nextCursor`	Cursor für die nächste Seite, sonst `null`
`incompleteExpands`	Expands, die für ein Asset mehr Einträge haben, als ihr `limit` zuließ

POST /cursor/continue liefert mit { "cursor": "<nextCursor>" } die nächste Seite. Der Cursor ist an Subscription und Benutzer gebunden und läuft nach einer Stunde ab; danach beginnen Sie die Abfrage neu. Behandeln Sie ihn als undurchsichtigen Wert.

Folgeseiten tragen immer die ungekürzten Stammangaben und nur das Expand object_data. Ein select und die übrigen Expands der ersten Seite gelten dort nicht. Für object_essentials, object_blocks und children auf jeder Seite rufen Sie POST /assets/expand je Asset auf.

Anlegen und aktualisieren

POST /asset schreibt ein Asset, POST /asset/bulk bis zu 100 in einer Transaktion. Docusnap365 entscheidet selbst, ob es das Asset schon kennt: Dann wird es aktualisiert, sonst angelegt. Ein neu angelegtes Asset beantwortet die API mit 201, ein aktualisiertes mit 200.

{
  "id": "9e2b7c11-1111-2222-3333-444455556666",
  "schemaId": "…",
  "object": {
    "name": "SRV01",
    "sourceType": "manual",
    "completenessLevel": 80
  },
  "objectData": { "serialNumber": "CZC811922L" }
}

Feld	Bedeutung
`schemaId`	Typ des Assets, Pflicht
`id`	frei gewählte Kennung innerhalb der Anfrage; sie kommt in der Antwort als `idPair.fakeId` zurück
`object.name`	Pflicht, höchstens 256 Zeichen; Leerzeichen am Anfang und Ende werden entfernt
`object.completenessLevel`	wie vollständig die Quelle ist; schützt vollständigere Datensätze davor, von ärmeren überschrieben zu werden
`objectData`	die Daten des Typs nach dessen Datendefinition; ein Aufruf ersetzt sie ganz
`essentials`, `facets`	Kurzansicht sowie ITAM- und ISMS-Daten

Ohne objectData ist object.id Pflicht, und das Asset wird aktualisiert. Ein vollständigerer vorhandener Datensatz, der nicht überschrieben werden darf, und ein Datensatz mit zu wenigen Identitätswerten werden abgelehnt. Die Antwort nennt die ID des Assets (id, idPair.dbId), ob es angelegt wurde (isCreate) und ob es geklappt hat (isSuccess, sonst errorMessage). Bei POST /asset/bulk liefert results ein Ergebnis je Eintrag in der Reihenfolge der Anfrage, zuzuordnen über idPair.fakeId, dazu successCount und failedCount. Ein Eintrag ohne object oder mit fehlendem oder zu langem Namen bricht den ganzen Aufruf mit 400 ab. Ein geschütztes Asset oder eines mit zu wenigen Identitätswerten wird übersprungen und trägt in results seine errorMessage; die übrigen Einträge werden geschrieben.

Der Status 200 bei POST /asset/bulk bedeutet nicht, dass alle Einträge gespeichert wurden. Prüfen Sie failedCount und results[].isSuccess.

Fehler

Fehler der API kommen als application/problem+json nach RFC 9457 mit status, errorCode, detail, instance und einer traceId. Werten Sie errorCode in der Anwendung aus; detail ist ein technischer englischer Satz, der sich ändern kann und Endanwendern nicht angezeigt wird. Bei Rückfragen an den Support nennen Sie die traceId. Ablehnungen beim Schreiben, etwa ein geschütztes Asset, kommen nicht als Problem-Antwort, sondern als Ergebnis mit errorMessage. Unterscheiden Sie beide Formen am Content-Type: application/problem+json gegenüber application/json. Die Meldungen in errorMessage zeigen Sie höchstens an.

Status	`errorCode`	Ursache	Maßnahme
400	`VALIDATION_FAILED`	Körper nicht lesbar, Pflichtfeld fehlt, unbekannter Operator, unbekannter `expandName`	Anfrage korrigieren
400	`INVALID_FORMAT`	`select` oder `search` ist kein JSON-Array aus Zeichenketten, oder ein Eintrag in `search` enthält mehr als ein `=`	Parameter korrigieren
400	`UNKNOWN_PATH`	Feld in `select`, `filter` oder `sort` unbekannt, oder `data.`-Pfad in der Hauptabfrage	Feldnamen prüfen; `data.`-Pfade nur in Expands
400	`FIELD_TYPE_MISMATCH`, `UNSUPPORTED_OPERATOR`	Wert oder Operator passt nicht zum Feld	Wert oder Operator anpassen
400	`INVALID_CURSOR`, `CURSOR_EXPIRED`, `CURSOR_SOURCE_MISMATCH`	Cursor beschädigt, älter als eine Stunde oder passt nicht zu `parentId` und `expandName`	Abfrage neu beginnen
401	`UNAUTHORIZED`	Schlüssel fehlt oder ist ungültig	Schlüssel prüfen
403	`FORBIDDEN`	Schlüssel hat nicht den nötigen Zugriff	Schlüssel mit passendem Zugriff verwenden
403	`CURSOR_USER_MISMATCH`, `CURSOR_DATA_SOURCE_MISMATCH`	Cursor stammt von einem anderen Benutzer oder einer anderen Subscription	eigene Abfrage beginnen
404	`NOT_FOUND`	Asset nicht vorhanden oder nicht sichtbar, oder unbekannter Endpunkt	ID und Rechte prüfen
429	`REST_REQUEST_QUOTA_EXCEEDED`	Kontingent aufgebraucht	bis `Retry-After` warten
500	`INTERNAL_ERROR`	unerwarteter Fehler	mit `traceId` an den Support
503	`SERVICE_UNAVAILABLE`	Kontingent ließ sich nicht prüfen; die Anfrage wurde nicht ausgeführt	später wiederholen

Kontingent

Jeder Aufruf eines der sieben Endpunkte zählt eine Anfrage gegen das Kontingent der Subscription (API- & MCP-Anfragen); REST-API und MCP teilen sich dieses Kontingent. Die Anfrage zählt auch dann, wenn sie danach scheitert, etwa an einem unbekannten Feld oder einem abgelaufenen Cursor. Nicht gezählt werden Anfragen, die schon an fehlendem Schlüssel (401), fehlendem Zugriff (403) oder einem unbekannten Endpunkt (404) scheitern. Zusätzliche Anfragen werden mit dem Zeitraum nicht zurückgesetzt, die enthaltenen schon. Sind beide aufgebraucht, antwortet die API mit 429 und führt die Anfrage nicht aus; auch abgelehnte Anfragen zählen. Bei begrenztem Kontingent tragen alle Antworten, auch Fehlerantworten, diese Kopfzeilen:

Kopfzeile	Inhalt
`X-RateLimit-Limit`	im Zeitraum enthaltene Anfragen
`X-RateLimit-Remaining`	noch verfügbare Anfragen, enthaltene und zusätzliche zusammen
`X-RateLimit-Extra-Remaining`	davon noch verfügbare zusätzliche Anfragen
`X-RateLimit-Reset`	Beginn des nächsten Zeitraums als Unix-Zeitstempel in Sekunden
`Retry-After`	nur bei `429`: Beginn des nächsten Zeitraums als HTTP-Datum

Bei unbegrenztem Kontingent fehlen diese Kopfzeilen.

Weiterführend

Die API-Referenz (in der Seitenleiste unter API-Referenz) – alle Endpunkte mit Parametern, Schemas und Beispielen
Datenmodell – Typen, Felder, Eigenschaften
API-Schlüssel verwalten – Schlüssel anlegen, Rechte, Ablauf
KI-Verbindungen – Verbrauch des Kontingents

​Adresse und Aufrufe

​Schlüssel und Rechte

​Assets und Typen

​Lesen und Abfragen

​Details laden

​Weiterblättern mit dem Cursor

​Anlegen und aktualisieren

​Fehler

​Kontingent

​Weiterführend

Adresse und Aufrufe

Schlüssel und Rechte

Assets und Typen

Lesen und Abfragen

Details laden

Weiterblättern mit dem Cursor

Anlegen und aktualisieren

Fehler

Kontingent

Weiterführend