Listen: Seitenwechsel, Filter, Sortierung, Felder und Erweiterung
Jede Liste der HIVE-API (Assets, Signale, Alarme, Arbeitsaufträge, Dokumente und alle weiteren) funktioniert gleich. Man lernt es einmal. Englische Fassung: Lists: pagination, filtering, sorting, fields and expansion. Die Parameter jeder Liste stehen in List parameters.
Die Antwort#
{
"object": "list",
"data": [ { "id": "alm_01m71xxn9ze26b4pq3dnxee9ms", "object": "alarm", "asset_id": "ast_01m71xxng7fzrvspnkgtw1t2kg", "expanded": {} } ],
"has_more": true,
"next_cursor": "c1.AQzIubxgQuAaae5Bh7r-gp9o...",
"total_count": null,
"total_count_is_lower_bound": null
}next_cursorist ein String, wennhas_moreden Werttruehat, undnull, wenn esfalseist. Etwas anderes kommt nie vor.- Bei
has_more: trueenthält die Antwort außerdem den HeaderLink: <https://api.hive.clerktree.com/v1/alarms?cursor=...&limit=20&state=open>; rel="next": dieselbe Abfrage mit dem neuen Cursor. total_countundtotal_count_is_lower_boundsindnull, solange Sie nichtcount=truesenden (siehe unten).
Seitenwechsel: limit und cursor#
limitist 1 bis 500, Standard 50. Jeder andere Wert ergibt400 invalid_requestmit dem Fehlercodeinvalid_limit.- Senden Sie den
next_cursoreiner Seite alscursor, um die folgende Seite zu erhalten. Wiederholen Sie das, bishas_moreden Wertfalsehat. - Es gibt kein
offsetund keinpage. Der Seitenwechsel arbeitet mit Schlüsselmengen (Keyset) und bleibt auch bei Tabellen mit Millionen Zeilen schnell. - Ein Cursor ist undurchsichtig. Lesen Sie ihn nicht aus, speichern Sie ihn nicht länger als einen Tag und senden Sie ihn nicht mit einer anderen Abfrage. Er ist an Ihren Mandanten, den Endpunkt, die Filter, die Sortierung und die API-Version gebunden und läuft 24 Stunden nach der Ausgabe ab. Ein Cursor, der mit etwas anderem verwendet wird, ein beschädigter, ein abgelaufener und ein Cursor eines anderen Mandanten ergeben alle denselben Fehler
400 invalid_cursor: beginnen Sie dann ohne Cursor von vorn. - Derselbe Cursor liefert bei unveränderten Daten dieselbe Seite.
Das Konsistenzversprechen#
Ein Durchlauf über eine Menge, die sich nicht ändert, liefert jede Zeile genau einmal. Während Zeilen hinzukommen, sich ändern und gelöscht werden, gilt:
- eine Zeile, deren Sortierwerte sich nicht ändern, wird höchstens einmal geliefert und nie übersprungen;
- eine Zeile, deren Sortierschlüssel sich während des Durchlaufs ändert, kann zweimal geliefert werden oder fehlen;
- eine Zeile, die zwischen zwei Seiten gelöscht wird, verursacht keinen Fehler; der Durchlauf setzt an der Position im Cursor fort.
Wenn Sie eine vollständige Kopie sich ändernder Daten brauchen, verwenden Sie die Änderungsströme und Exporte statt eines langen Listendurchlaufs.
Filter#
feld=wert ist Gleichheit. feld[operator]=wert verwendet einen Operator. Mehrere Parameter werden mit UND verknüpft; ein ODER gibt es nicht (verwenden Sie in oder zwei Anfragen). Jede Liste legt fest, welche Felder mit welchen Operatoren filterbar sind (List parameters).
| Operator | Bedeutung | Gilt für |
|---|---|---|
eq (die bloße Form) | gleich | alle Typen |
ne | ungleich | alle Typen |
gt, gte, lt, lte | größer, größer oder gleich, kleiner, kleiner oder gleich | Zahlen, Zeitstempel, Datumswerte |
in, nin | in / nicht in einer kommagetrennten Liste mit höchstens 100 Werten | Strings, Aufzählungen, Zahlen, Referenzen |
contains, prefix | enthält / beginnt mit, ohne Unterscheidung von Groß- und Kleinschreibung | Felder, die als textsuchbar deklariert sind |
is_null | true findet leere Werte, false nicht leere Werte | alle Typen |
Werte sind typisiert:
- Zeitstempel: RFC 3339 mit Zeitzonenangabe, in UTC normalisiert:
2026-11-09T00:00:00Zoder2026-11-09T01:00:00+01:00. Ein Datum allein wird abgelehnt. - Datumswerte (Felder mit der Endung
_on):JJJJ-MM-TT. - Zahlen: einfache Dezimalzahlen; Mengenangaben werden nach ihrem Zahlenwert in der gespeicherten Einheit gefiltert (je Feld dokumentiert).
- Wahrheitswerte:
trueoderfalse. Referenzen: die ID mit ihrem Präfix (ast_...). Aufzählungen: einer der dokumentierten Werte. inundnin:state[in]=open,acknowledgedoderstate[in]=open&state[in]=acknowledged. Ein Wert darf kein Komma enthalten.- Ein Vergleich trifft nie einen leeren Wert:
due_on[ne]=2026-11-20liefert keine Arbeitsaufträge ohne Fälligkeitsdatum; verwenden Sie dafürdue_on[is_null]=true.
Höchstens 5 Filter, 100 Werte in einer in-Liste, 3 Sortierfelder und 3 Erweiterungen je Anfrage. Ein Filter auf ein Feld, das nicht als filterbar deklariert ist, ein für das Feld nicht erlaubter Operator, ein Wert des falschen Typs und ein Parameter, den die Liste nicht kennt, werden mit 400 invalid_request abgelehnt; sie werden nie ignoriert. Die Fehlereinträge nennen den Parameter und einen der Codes invalid_filter_field, invalid_filter_operator, invalid_type, invalid_enum, too_many_items, unknown_field.
Beispiele (Musterwerk):
GET /v1/alarms?state=open&asset_id[in]=ast_01m71xxng7fzrvspnkgtw1t2kg,ast_01m71xxpcwfz1snpsm3pqdqrjc&sort=-raised_at&expand=asset&limit=20
GET /v1/work-orders?created_at[gte]=2026-11-09T00:00:00Z&title[contains]=bearing&fields=id,key,title,state
GET /v1/assets?asset_type_id[is_null]=trueFilterwerte werden nie in unsere Protokolle geschrieben; nur die Feldnamen und Operatoren.
Sortierung#
sort=raised_at,-key: eine kommagetrennte Liste mit bis zu 3 sortierbaren Feldern, - für absteigend. Der Server hängt id als letzten Schlüssel an, damit die Reihenfolge eindeutig ist; er übernimmt die Richtung des letzten Feldes, das Sie angegeben haben. Standard ist -id (neueste zuerst), sofern die Liste keinen anderen Standard dokumentiert. Ein nicht sortierbares Feld, ein wiederholtes Feld, id an anderer Stelle als am Ende oder mehr als 3 Felder ergeben 400 invalid_sort_field. Leere Werte stehen bei aufsteigender Sortierung zuletzt und bei absteigender zuerst.
Felder: fields#
fields=key,name liefert nur diese Felder der obersten Ebene sowie id und object. Eine Punktebene wählt einen Teil eines Objekts oder jedes Objekts eines Arrays: fields=key,external_refs.system. Ein unbekannter Name ergibt 400 invalid_field_selection. Eine Liste mit Erweiterungen behält immer das Feld expanded.
Erweiterung: expand#
expand=asset fügt die referenzierten Objekte unter expanded.asset hinzu und behält das Feld asset_id. Erlaubt sind nur Namen, die die Liste deklariert, höchstens 3 und nur eine Ebene tief (asset.parent wird abgelehnt). Ohne expand lautet das Feld "expanded": {}.
Eine Erweiterung ist ein Lesezugriff mit Ihren Berechtigungen: Ein Objekt, das Sie nicht lesen dürfen oder das nicht existiert, ist in expanded null, nie ein Fehler und nie Daten. Felder eines erweiterten Objekts wählen Sie mit fields[asset]=key,name.
Zählen: count=true#
count=true fügt total_count hinzu: genau bis 10.000. Darüber ist total_count gleich 10000 und total_count_is_lower_bound gleich true. Ohne count=true wird nichts gezählt. Dauert das Zählen zu lange, wird die Seite trotzdem geliefert und total_count ist null.
Fehler#
| Situation | Antwort |
|---|---|
| Ungültiger Parameter | 400 invalid_request, je Problem ein Eintrag in errors[] mit parameter |
| Cursor ungültig, abgelaufen oder mit anderer Abfrage, anderem Mandanten, Endpunkt oder anderer Version verwendet | 400 invalid_cursor (immer derselbe Inhalt) |
| Die Datenbank braucht für eine Seite mehr als 2 Sekunden | 504 timeout, keine Teildaten; Filter einengen und erneut versuchen |