Paginierung und Filter

Sammlungen sind immer seitenweise

Jede Liste in der API — Spaces, Grids, Einträge, Ansichten, Freigaben — hat dieselbe Hülle:

{
  "page": 1,
  "pageSize": 300,
  "size": 2,
  "numberOfItems": 1450,
  "numberOfPages": 5,
  "items": [ … ]
}

Feld	Bedeutung
page	Die angeforderte Seite, 1-basiert
pageSize	Die angeforderte Seitengröße
size	Wie viele Einträge auf dieser Seite liegen
numberOfItems	Gesamtzahl über alle Seiten
numberOfPages	Anzahl der Seiten

Gesteuert wird über zwei Parameter:

Parameter	Vorgabe
pageIndex	1	Muss größer als 0 sein, sonst 400
pageSize	300	Muss größer als 0 sein, sonst 400. Bei …/grids/{gridId}/query ist die Vorgabe 50

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE$GRID/entities?pageIndex=2&pageSize=100"

Eine überzählige Seite ist kein Fehler

Fordern Sie eine Seite jenseits des Endes an, kommt 200 mit leerem items — nicht 404. Eine Schleife endet also sauber, wenn items leer ist oder page gleich numberOfPages ist.

Alle Einträge holen:

seite=1
while :; do
  antwort=$(curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
    "$BASE$GRID/entities?layout=field&pageSize=300&pageIndex=$seite")
  anzahl=$(echo "$antwort" | python3 -c 'import json,sys; print(len(json.load(sys.stdin)["items"]))')
  [ "$anzahl" -eq 0 ] && break
  echo "$antwort"
  seite=$((seite + 1))
done

Filtern

filter erwartet ein JSON-Objekt, URL-kodiert, und gilt für GET …/grids/{gridId}/entities.

Der einfachste Fall — ein Feld, ein Operator, ein Wert:

{ "6512cc…": { "$eq": "offen" } }

FILTER='{"6512cc…":{"$eq":"offen"}}'
curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  --get --data-urlencode "filter=$FILTER" \
  "$BASE$GRID/entities?layout=field"

--data-urlencode spart Handarbeit

Filter enthalten {, " und $. Mit curl --get --data-urlencode müssen Sie nicht selbst kodieren.

Operatoren

Operator	Bedeutung
$eq	Gleich
$gt	Größer als — auch für Datum und Zeit
$lt	Kleiner als
$substring	Enthält den Teiltext
$isEmpty	Feld ist leer
$hasAnyOf	Enthält mindestens einen der Werte
$hasAllOf	Enthält alle Werte
$hasNoneOf	Enthält keinen der Werte
$isActor	Feld verweist auf die aufrufende Identität
$isUpdated	Feld wurde geändert
$updated	Feld wurde von einem Wert auf einen anderen geändert; nimmt { "from": …, "to": … }, beide Angaben sind einzeln zulässig

Verknüpfungen:

Operator	Bedeutung
$and	Alle Teilbedingungen müssen zutreffen
$or	Mindestens eine Teilbedingung muss zutreffen
$not	Kehrt die Bedingung um

$and und $or nehmen ein Array von Bedingungsobjekten, $not genau ein Objekt:

{
  "$or": [
    { "6512cc…": { "$gt": "2026-01-01T00:00:00+01:00" } },
    { "6512dd…": { "$eq": "dringend" } }
  ]
}

{ "$not": { "6512dd…": { "$eq": "erledigt" } } }

Mehrere Schlüssel nebeneinander in einem Objekt werden verundet:

{
  "6512cc…": { "$eq": "offen" },
  "6512dd…": { "$substring": "Rechnung" }
}

Ausdrücke im Filterwert

Werte dürfen einen Ausdruck in doppelten geschweiften Klammern tragen, der beim Auswerten aufgelöst wird:

{ "6512dd…": { "$gt": "{{today()}}" } }

→ ApptiveScript

Filter und Ansichten

Hat die angesprochene Ansicht bereits einen Filter, entscheidet compose, was mit dem mitgegebenen Filter geschieht:

compose	Wirkung
true (Vorgabe)	Beide Filter werden verundet
false	Der mitgegebene Filter ersetzt den der Ansicht

Filter dürfen ausgeblendete Felder nennen

Aufgelöst wird gegen das Schema des zugrunde liegenden Grids, nicht gegen die Feldauswahl der Ansicht.

Was schiefgeht

Antwort	Ursache
400 „Filter definition is malformed"	Kein gültiges JSON oder unbekannter Aufbau
400 mit Feldkennung	Der genannte Schlüssel ist kein Feld dieses Grids

Ein häufiger Stolperstein sind typografische Anführungszeichen aus einem Editor: {"name":"x"} mit „" statt " ist kein JSON und ergibt 400.

Sortieren

sorting erwartet ebenfalls JSON, URL-kodiert:

{ "6512cc…": { "$order": "ascending" } }

Richtungen sind ascending und descending. Mehrere Kriterien schreibt man als Array — sie werden in der angegebenen Reihenfolge angewandt:

[
  { "6512dd…": { "$order": "descending" } },
  { "6512cc…": { "$order": "ascending" } }
]

SORT='[{"6512dd…":{"$order":"descending"}}]'
curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  --get --data-urlencode "sorting=$SORT" \
  "$BASE$GRID/entities?layout=field"

Neben $order darf ein Kriterium eine Funktion tragen, die vor dem Vergleich auf den Wert angewandt wird — etwa Kleinschreibung oder die Entfernung zu einem Ort. Welche Funktionen ein Feldtyp unterstützt, prüft das Backend; passt sie nicht, antwortet es mit 400.

Ohne sorting gilt die Sortierung, die in der Ansicht hinterlegt ist.

Suchen statt filtern

Wenn Sie nicht nach einem bestimmten Feld filtern, sondern schlicht einen Text suchen wollen:

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE$GRID/query?matching=Rechnung&pageSize=20"

Die Treffer sind auf die ersten vier Felder des Schemas beschränkt. → Grids