Wie Paginierung und Suche funktionieren
Listen in der Sally API werden seitenweise ausgeliefert, und für die Suche hat jede Ressource ihren eigenen Endpunkt. Diese Seite erklärt die Seitenhülle, warum die Suche ihre Parameter im Request-Body erwartet und wie Suchbegriffe abgeglichen werden.
Schnellnavigation
1. Paginierung
Seitenweise Listen-Endpunkte nehmen ?page (beginnend bei 1, Standard 1) und ?pageSize (Standard 25, höchstens 100). Die Antwort ist eine Hülle:
{ "page": 1, "pageSize": 25, "total": 137, "hasMore": true, "items": [ … ] }
total zählt alle Treffer über alle Seiten, und hasMore sagt dir, ob noch eine Seite folgt. Ein paar kleine Listen werden nicht geblättert und liefern ein einfaches JSON-Array. Welche Art ein Endpunkt liefert, steht in der Referenz.
2. Such-Endpunkte
Jede durchsuchbare Ressource hat einen POST …/search-Endpunkt, der seine Parameter im Request-Body erwartet. Das ist Absicht: Ein Suchbegriff in einer URL läuft mit Leerzeichen, Umlauten und Prozentzeichen in Kodierungsprobleme, im Body nicht.
POST /v1.0/directories/{directoryId}/appointments/search
{ "search": "Q4 Planung", "from": "2026-09-01T00:00:00Z" }
Ein Such-Body hat immer genau ein Freitextfeld namens search, das auf einmal über alle passenden Textfelder der Ressource sucht, dazu die strukturellen Filter der Ressource sowie page und pageSize. Die Antwort hat dieselbe Hülle wie der passende Listen-Endpunkt. Durchsuchbar sind Termine, Zusammenfassungen, Aufgaben, Ordner und die Nutzer eines Unternehmenskontos.
Die einfachen GET-Listen bleiben reine Listen-Endpunkte. Der Such-Endpunkt kommt hinzu, er ersetzt sie nicht.
3. Wie gesucht wird
- Teilstring ohne Rücksicht auf Groß- und Kleinschreibung: Der Begriff passt irgendwo im Wert, nicht nur am Anfang.
- Wörtlich:
%,_und*sind gewöhnliche Zeichen, keine Platzhalter. - Bereinigt: Leerzeichen am Anfang und Ende werden entfernt, und ein leerer Begriff heißt kein Filter.
- Manche Endpunkte verlangen eine Mindestlänge, die die Referenz am Endpunkt nennt.