Pagination, Filterung und Sortierung

Collection-Endpoints verwenden dasselbe Abfragemodell. Jede Operation listet die exakten öffentlichen skalaren Felder auf, die für Filterung und Sortierung zur Verfügung stehen.

Pagination

Parameter	Standard	Einschränkung
`page`	`1`	Einsbasierter Integer
`pageSize`	`100`	Integer von `1` bis `1000`

curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=250'

Zuverlässige Seitenverarbeitung

Offset-basierte Pagination ist kein Snapshot. Parallele Erstellungen oder Aktualisierungen können spätere Seiten beeinflussen. Verwenden Sie für wiederholbare inkrementelle Verarbeitung einen stabilen fachlichen Checkpoint und ein explizites Zeitfenster, statt davon auszugehen, dass Seiten unverändert bleiben.

Seitenmetadaten und Randfälle

Collection-Responses enthalten page, pageSize, totalPages, totalElements und items. Der öffentliche Vertrag definiert kein separates Sonderverhalten für Seiten außerhalb des gültigen Bereichs und keinen exakten totalPages-Wert bei null Treffern. Verwenden Sie die Werte aus der Response, statt Annahmen fest zu codieren.

Sortierung

Verwenden Sie genau ein vom Endpoint unterstütztes skalares Feld. Stellen Sie - voran, um absteigend zu sortieren.

sort=createdAt
sort=-updatedAt

Mehrere Felder und Leerzeichen werden abgelehnt. Null-Werte stehen bei aufsteigender Sortierung am Anfang und bei absteigender Sortierung am Ende.

Ein einzelnes Sortierfeld ist weder ein Idempotenz- noch ein Snapshot-Mechanismus. Speichern Sie verarbeitete Ressourcen-IDs oder Quell-Checkpoints, wenn Duplikate schädlich wären.

Created-at-Zeitfenster

Wo dokumentiert, sind createdAtFrom und createdAtTo inklusive ISO-8601-UTC-Zeitstempel mit abschließendem Z.

createdAtFrom=2026-08-01T00:00:00.000Z
createdAtTo=2026-08-31T23:59:59.999Z

Filteroperatoren

=  !=  >  >=  <  <=
IN (...)
CONTAINS
STARTS_WITH
ENDS_WITH
IS NULL
IS NOT NULL

AND bindet stärker als OR. Verwenden Sie Klammern, wenn die gewünschte Gruppierung ausdrücklich erkennbar sein soll.

blocked=false AND (countryCode="DE" OR countryCode="AT")

String-Werte und Anführungszeichen

String-Vergleiche sind case-insensitive. Folgende Formen werden unterstützt:

lastName=Example
lastName="Example"
lastName='Example'

Werte mit Leerzeichen müssen in Anführungszeichen gesetzt werden:

lastName='van Example'
lastName="van Example"

Escapen Sie ein Apostroph mit einem Backslash:

lastName='O\'Example'
lastName="O\'Example"

Die Beispiele zeigen decodierte Filterausdrücke. URL-encodieren Sie den vollständigen Query-Wert. curl --data-urlencode wird empfohlen.

curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'filter=lastName="van Example"'

`IN`, null und Textoperatoren

countryCode IN ("DE","AT","CH")
divisionId IS NULL
privateEmail IS NOT NULL
lastName STARTS_WITH "M"
additionalInfo CONTAINS "Building B"

Formales Ausdrucksmodell

expression  = term, { "OR", term };
term        = factor, { "AND", factor };
factor      = comparison | "(", expression, ")";
comparison  = field, operator, value;

Der Endpoint bestimmt, welche Felder und Operatoren gültig sind. Ein syntaktisch gültiger Filter kann weiterhin mit UNSUPPORTED_FILTER_FIELD oder UNSUPPORTED_FILTER_OPERATOR fehlschlagen.

Grenzen der Query-Größe

Der öffentliche Vertrag nennt keine separate maximale Länge für Filterausdrücke. Halten Sie Ausdrücke begrenzt, bevorzugen Sie mehrere gezielte Anfragen statt eines übermäßig komplexen Ausdrucks und behandeln Sie reguläre Request-Validierungs- oder Größenlimitantworten.

Filterfehler

Fehlercode	Ursache	Maßnahme
`INVALID_FILTER_SYNTAX`	Ausdruck kann nicht geparst werden	Quoting, Escaping, Klammern und `IN`-Syntax prüfen
`UNSUPPORTED_FILTER_FIELD`	Feld ist auf diesem Endpoint nicht filterbar	Ein von der Operation aufgeführtes Feld verwenden
`UNSUPPORTED_FILTER_OPERATOR`	Operator ist für das Feld nicht erlaubt	Kompatiblen Operator verwenden
`UNSUPPORTED_SORT_FIELD`	Sortierfeld ist nicht erlaubt	Ein dokumentiertes skalares Feld verwenden
`UNKNOWN_QUERY_PARAMETER`	Query-Name wird nicht unterstützt	Unbekannten Parameter entfernen

Erste Schritte

Architektur & Konzepte

Integrationsleitfäden

Betrieb

Pagination, Filterung und Sortierung

Zuverlässige Seitenverarbeitung

Seitenmetadaten und Randfälle

Sortierung

Created-at-Zeitfenster

Filteroperatoren

String-Werte und Anführungszeichen

`IN`, null und Textoperatoren

Formales Ausdrucksmodell

Grenzen der Query-Größe

Filterfehler

​Pagination

​Zuverlässige Seitenverarbeitung

​Seitenmetadaten und Randfälle

​Sortierung

​Created-at-Zeitfenster

​Filteroperatoren

​String-Werte und Anführungszeichen

​IN, null und Textoperatoren

​Formales Ausdrucksmodell

​Grenzen der Query-Größe

​Filterfehler

Pagination

Zuverlässige Seitenverarbeitung

Seitenmetadaten und Randfälle

Sortierung

Created-at-Zeitfenster

Filteroperatoren

String-Werte und Anführungszeichen

`IN`, null und Textoperatoren

Formales Ausdrucksmodell

Grenzen der Query-Größe

Filterfehler