REST-API-Grundlagen

Diese Seite erklärt die Konventionen, denen die REST-API für die Verwaltung folgt. Die Routen selbst sind nach Bereich auf den am Ende verlinkten Referenzseiten aufgelistet.

Pfade

Jeder Verwaltungspfad ist auf Ihre Organisation beschränkt:

https://<your host>/tenant/<tenantId>/api/<resource>

Auf den Referenzseiten sind Pfade ab /api/... angegeben; stellen Sie /tenant/<tenantId> davor. Beispiel: /api/iot/devices bedeutet https://<your host>/tenant/<tenantId>/api/iot/devices.

Senden Sie bei jedem Aufruf Authorization: Bearer <API key>. Siehe Authentifizierung.

Anfragen

Anfragetexte sind JSON: Senden Sie Content-Type: application/json. Eine Ausnahme ist der Firmware-Upload, der multipart/form-data verwendet.
Die meisten Anfragetexte sind strikt: Ein Feld, das die Route nicht kennt, wird mit 400 abgelehnt und nie stillschweigend ignoriert. Prüfen Sie die Schreibweise, wenn Sie einen 400 für ein Feld erhalten, das richtig aussieht.
PATCH ändert nur die Felder, die Sie senden. PUT ersetzt das Ganze (die Alarmregeln eines Profils, eine Platzierung, einen Einstellungsabschnitt).
Ein auf null gesetztes Feld wird geleert, sofern das Feld null zulässt.
IDs sind UUIDs (6f1c0a2e-…). Eine fehlerhafte ID im Pfad führt meist zu einem 400 oder einem 404.

Antworten

Antworten sind JSON. Ein einzelner Datensatz wird in seinen Namen eingeschlossen: { "device": {...} }, { "alarm": {...} }.
Eine Liste wird als Array zusammen mit der Gesamtanzahl geliefert. Der Name des Arrays hängt von der Route ab: { "devices": [...], "total": 42 }, { "items": [...], "total": 7 } oder { "data": [...], "total": 3 }. Jede Referenzseite zeigt den Namen.
Eine Antwort, die ein Geheimnis enthält (ein neues Gerätetoken, einen neuen API-Schlüssel, ein Webhook-Signiergeheimnis), wird mit Cache-Control: no-store gesendet und ist die einzige Stelle, an der das Geheimnis erscheint.

Zeitangaben

Es werden zwei Formate verwendet. Jede Referenzseite gibt an, welches.

Format	Verwendung	Beispiel
ISO 8601 als Text, UTC	Datensatzfelder (`createdAt`, `lastActivityAt`), die meisten Filter, Webhook-Payloads	`"2026-11-05T10:00:00.000Z"`
Millisekunden seit dem 1. Januar 1970, UTC	Telemetrie (`ts`, `from`, `to`), Alarmzeiten (`startTs`, `openedAt`)	`1762336800000`

Datumsbereichsfilter der Form createdFrom=2026-10-01&createdTo=2026-10-15 verwenden ganze Tage im Format JJJJ-MM-TT in UTC; beide Tage sind eingeschlossen.

Listen

Listen werden serverseitig seitenweise ausgegeben. Es gibt zwei Seitenstile:

Stil	`page` beginnt bei	Verwendet von (Beispiele)
1-basiert	`1`	Geräte, Gerätprofile, Alarme, Standorte und Anlagen, API-Schlüssel, Webhooks und deren Zustellungen
0-basiert	`0`	LoRaWAN-Gateways und -Geräte, Befehlsverlauf eines Geräts mit `page`, Einstellungsaufträge und Baselines von Geräten, MCP-verbundene Apps

Die Referenzseiten nennen die Basis jeder Liste. Die gemeinsamen Parameter:

Parameter	Bedeutung	Grenzen
`page`	Seitennummer	bis 10.000 oder 100.000, je nach Liste
`pageSize`	Zeilen pro Seite	Standard 20, höchstens 100 (einige Listen erlauben 200 oder 500, wie angegeben)
`search`	Freitext, der in Namen und ähnlichen Feldern gesucht wird	bis 128 bzw. 200 Zeichen
`sort`	`field:asc` oder `field:desc`, bis zu drei, durch Kommas getrennt	nur die Felder, die die Route auflistet; alles andere führt zu `400`
Filter	Je Route benannt	siehe unten

Mehrere 0-basierte Listen akzeptieren aus Gründen der Kompatibilität mit älteren Clients auch limit für pageSize und q für search.

Sortierung

GET /api/iot/devices?sort=lastSeen:desc
GET /api/iot/lorawan/gateways?sort=status:asc,name:asc

Ein unbekanntes Feld wird mit 400 abgelehnt, zum Beispiel „Cannot sort by „x“. Sortable fields: name, connection, lastSeen, createdAt.“ Bei den 0-basierten Listen werden Gleichstände über die ID aufgelöst, damit das Blättern stabil bleibt.

Filter

Art	Form	Beispiel
Einer aus einer Menge	kommagetrennte Liste	`status=OPEN,ACKNOWLEDGED`
IDs	kommagetrennte Liste von UUIDs, höchstens 100	`deviceId=…,…`
Schalter	`true` oder `false`	`online=true`
Tagesbereich	`<name>From`, `<name>To`	`createdFrom=2026-11-01`
Zahlenbereich	`<name>Min`, `<name>Max`	wo eine Route ihn anbietet

Lassen Sie einen Parameter weg, statt ihn leer zu senden: Die meisten Listen ignorieren einen leeren Parameter, einige lehnen ihn jedoch ab.

Alle Seiten lesen

// Node.js 18+: read every device, 100 at a time (a 1-based list)
const base = `https://${host}/tenant/${tenant}/api/iot/devices`;
const all = [];
for (let page = 1; ; page++) {
  const res = await fetch(`${base}?page=${page}&pageSize=100&sort=createdAt:asc`, {
    headers: { Authorization: `Bearer ${key}` },
  });
  if (res.status === 429) { await new Promise((r) => setTimeout(r, Number(res.headers.get('Retry-After') ?? 60) * 1000)); page--; continue; }
  const { devices, total } = await res.json();
  all.push(...devices);
  if (all.length >= total || devices.length === 0) break;
}

Sortieren Sie nach einem Feld, das sich nicht ändert (createdAt), wenn Sie eine Liste durchblättern, die andere gerade ändern.

Änderungen durch andere

Manche Schreibvorgänge prüfen, ob der Datensatz sich seit dem Lesen nicht geändert hat:

Wo	Wie	Bei einem Konflikt
Gerätprofile	Senden Sie die `version` des Profils als `expectedVersion` im `PATCH`-Body	`409`, `details.reason` = `stale_profile`
Gerätеeinstellungsabschnitte	Senden Sie das `ETag` des Abschnitts in einem `If-Match`-Header	`412`, `details.reason` = `rev_mismatch`; `428` ohne `If-Match`

Die Alarmregeln eines Profils haben keine solche Prüfung: Ein PUT ersetzt die ganze Menge, daher lesen Sie die Regeln unmittelbar vor einer Änderung.

Lesen Sie erneut, wenden Sie Ihre Änderung auf die aktuelle Kopie an und senden Sie sie erneut.

Nicht gefunden und nicht erlaubt

Ein Datensatz einer anderen Organisation oder einer, den Sie nicht lesen dürfen, antwortet mit 404, wie ein nicht vorhandener Datensatz. Eine Route, die Sie gar nicht verwenden dürfen, antwortet mit 403. Den Fehlertext und alle Statuscodes finden Sie unter Fehler und Ratenbegrenzung.

Berechtigungen

Jede Route nennt die Berechtigung, die sie benötigt, dieselbe Berechtigung, die auch die App prüft. Die Referenzseiten nennen sie für jede Route, zum Beispiel iot_device.devices.read. Geben Sie einem Schlüssel diese Berechtigung unter Modulberechtigungen. Eine Berechtigung, die nur die Rolle Owner hat, kann einem Schlüssel nicht gegeben werden.

Routenreferenzen

Bereich	Seite
Geräte, Zugangsdaten, Verbindung, Protokoll, Gerätprofile	Geräte- und Profil-API
Neueste Werte, Verlauf, Attribute	Telemetrie- und Attribut-API
Befehle und der Befehlskatalog	Befehls-API
Alarme, Alarmregeln, Stummschaltungen	Alarm-API
Standorte, Anlagen, Platzierung, Beziehungen	Standort- und Anlagen-API
Firmware-Pakete, Rollouts, Gerätеeinstellungen	Firmware- und Geräteeinstellungs-API
LoRaWAN-Gateways, Geräte, Kopplung, Frames	LoRaWAN-API
Webhooks	Webhooks
API-Schlüssel	Authentifizierung
LoRaWAN-Codecs	Codec-API