Eine REST API, die nur alle Datensätze auf einmal zurückgibt, ist wenig nützlich – besonders wenn dein Dataset hunderte oder tausende Einträge enthält. Genau hier kommen Query-Parameter ins Spiel: Sie ermöglichen es dir, gezielt nach bestimmten Datensätzen zu suchen, Ergebnisse zu filtern, zu sortieren und seitenweise abzurufen.
In diesem Artikel erklären wir alle Query-Parameter der instantapi.io Daten-API – mit konkreten URL-Beispielen, JSON-Antworten und Hinweisen zur Kombination mehrerer Parameter. Als durchgehendes Beispiel nutzen wir einen Produktkatalog mit den Feldern id, name, kategorie, marke, preis und auf_lager.
Alle Beispiele in diesem Artikel gehen von folgender Basis-URL aus: https://api.instantapi.io/v1/produkte/data. Ersetze produkte durch den Slug deines eigenen Datasets. Der Header x-api-key ist bei jeder Anfrage erforderlich.
Überblick: Alle Query-Parameter
| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
limit | integer | 100 | Maximale Anzahl zurückgegebener Datensätze (max. 1000) |
offset | integer | 0 | Anzahl der übersprungenen Datensätze (für Pagination) |
sort | string | – | Spaltenname, nach dem sortiert wird |
order | asc / desc | asc | Sortierrichtung: aufsteigend oder absteigend |
search | string | – | Volltextsuche über alle Textspalten (ILIKE) |
{spalte} | string / number | – | Exakter Filter: Wert muss genau übereinstimmen |
{spalte}__gte | number / date | – | Größer oder gleich (≥) |
{spalte}__gt | number / date | – | Strikt größer als (>) |
{spalte}__lte | number / date | – | Kleiner oder gleich (≤) |
{spalte}__lt | number / date | – | Strikt kleiner als (<) |
{spalte}__not | string / number | – | Ungleich (!=) – schließt einen Wert aus |
{spalte}__in | string | – | Einer von mehreren Werten (kommagetrennt) |
{spalte}__contains | string | – | Teilstring-Suche in einer einzelnen Spalte (ILIKE) |
Pagination: limit und offset
Wenn dein Dataset viele Einträge enthält, willst du sie nicht alle auf einmal laden. Mit limit und offset kannst du die Ergebnisse seitenweise abrufen – das nennt sich Offset-basierte Pagination.
Pagination wie ein Buch mit Lesezeichen
limit ist die Anzahl der Seiten, die du auf einmal liest. offset ist dein Lesezeichen – es sagt der API, an welcher Stelle sie anfangen soll. Wenn du 100 Produkte in Zehner-Blöcken durchblättern möchtest: erste Anfrage offset=0, zweite offset=10, dritte offset=20 – und so weiter.
Erste Seite (10 Produkte)
Zweite Seite
Die API-Antwort enthält immer die Felder total, limit und offset, mit denen du die Pagination steuern kannst:
Mit total weißt du, wie viele Datensätze insgesamt gefunden wurden. Wenn offset + limit >= total, hast du die letzte Seite erreicht. Diese drei Felder reichen aus, um in deiner App eine vollständige Paginierungslogik zu bauen.
Wähle limit so, dass es zur Darstellung in deiner App passt – nicht größer als nötig. Sehr große Limits (z. B. 1000+) können die Antwortzeit erhöhen und mehr Bandbreite verbrauchen.
Sortierung: sort und order
Mit sort und order bestimmst du, in welcher Reihenfolge die Datensätze zurückgegeben werden. sort nimmt den Namen einer Spalte entgegen, order bestimmt die Richtung.
Produkte nach Preis aufsteigend (günstigste zuerst)
Produkte nach Preis absteigend (teuerste zuerst)
Produkte alphabetisch nach Name
Wird order weggelassen, sortiert die API standardmäßig aufsteigend (asc). Wird auch sort weggelassen, werden die Datensätze in der Reihenfolge zurückgegeben, in der sie gespeichert wurden (nach id aufsteigend).
Volltextsuche: search
Der Parameter search durchsucht alle Textspalten, die beim Dataset als „durchsuchbar" markiert sind, nach dem angegebenen Begriff. Die Suche ist nicht case-sensitiv und findet auch Teilstrings – ähnlich wie eine Datenbanksuche mit LIKE %suchbegriff%.
Nach Produkten suchen, die „kabel" im Namen oder in der Beschreibung enthalten
Beispielantwort:
Welche Spalten durchsucht werden, steuerst du beim Anlegen des Datasets im Dashboard unter „Durchsuchbar". Aktiviere dort nur Textspalten – Zahlen- oder Boolean-Felder macht es wenig Sinn zu durchsuchen.
Spaltenfilter: ?spaltenname=wert
Neben der Volltextsuche unterstützt die API auch exakte Filter auf einzelne Spalten. Dafür gibst du den Spaltennamen direkt als Query-Parameter an. Die Filterung ist exakt – der Wert muss vollständig übereinstimmen.
Nur Produkte der Kategorie „Elektronik"
Nur Produkte der Marke „TechPro"
Nur Produkte, die auf Lager sind
Boolean-Felder werden als true oder false (Kleinbuchstaben) übergeben. Zahlenwerte können ebenfalls direkt gefiltert werden:
Produkte mit einem Preis von genau 29.90
Erweiterte Filteroperatoren
Für anspruchsvollere Abfragen unterstützt die API Filteroperatoren über das __suffix-System. Du hängst den Operator einfach mit doppeltem Unterstrich an den Spaltennamen: spalte__operator=wert.
Vergleichsoperatoren: __gte, __gt, __lte, __lt
Mit diesen Operatoren kannst du Wertebereiche einschränken – ideal für Preisfilter, Datumsfelder oder numerische Kennzahlen.
Merkhilfe: gte = "greater than or equal"
gte = greater than or equal (≥) · gt = greater than (>) · lte = less than or equal (≤) · lt = less than (<). Diese Kürzel sind aus SQL und den meisten APIs bekannt.
Ausschluss-Filter: __not
Mit __not schließt du einen bestimmten Wert aus. Alle anderen Werte werden zurückgegeben.
Mehrfachauswahl: __in
Mit __in kannst du mehrere Werte kommagetrennt angeben. Ein Datensatz wird zurückgegeben, wenn er einem der angegebenen Werte entspricht – ein logisches ODER innerhalb einer Spalte.
Teilstring-Suche in einer Spalte: __contains
Während search alle Textspalten durchsucht, begrenzt __contains die Suche auf eine konkrete Spalte. Groß-/Kleinschreibung wird dabei ignoriert.
Alle Filterwerte werden als Strings übergeben. Die Datenbank übernimmt die Typkonvertierung automatisch. Bei Vergleichsoperatoren (__gte etc.) solltest du darauf achten, dass die Spalte tatsächlich einen numerischen oder Datums-Typ hat – sonst ist das Verhalten ggf. lexikografisch statt numerisch.
Parameter kombinieren
Die eigentliche Stärke der Query-Parameter zeigt sich erst, wenn du sie kombinierst. Alle Parameter können gleichzeitig in einer URL verwendet werden – sie werden als logisches UND verknüpft.
Beispiel 1: Elektronik-Produkte, auf Lager, nach Preis sortiert
Beispiel 2: Suche nach „Kabel", begrenzt auf 5 Ergebnisse
Beispiel 3: Alle TechPro-Produkte, zweite Seite à 20 Einträge
Beispiel 4: Preisbereich + Mehrfachkategorie + Sortierung
Beispiel 5: Alles auf Lager, nicht ausverkauft, Name enthält „Pro"
Vollständige Beispielanfrage mit curl:
Die Antwortstruktur verstehen
Jede erfolgreiche GET-Anfrage an /data gibt ein JSON-Objekt mit vier Feldern zurück:
Das Feld total gibt die Anzahl aller Datensätze zurück, die den Filterbedingungen entsprechen – unabhängig von limit und offset. Damit kannst du in deiner App die Gesamtanzahl der Seiten berechnen: Math.ceil(total / limit).
| Feld | Typ | Bedeutung |
|---|---|---|
total | integer | Gesamtanzahl der Datensätze (mit aktiven Filtern) |
limit | integer | Maximale Anzahl in diesem Response |
offset | integer | Anzahl übersprungener Datensätze |
data | array | Die eigentlichen Datensätze |
Fazit: Mächtige Abfragen mit einfachen Parametern
Die Query-Parameter der instantapi.io API geben dir alles, was du für praxistaugliche Datenabfragen brauchst: Pagination für große Datasets, Sortierung für eine sinnvolle Darstellung, Volltextsuche für Suchfelder, exakte Spaltenfilter und – neu – erweiterte Operatoren für Wertebereiche, Mehrfachauswahl und Teilstring-Suchen. Alles kombinierbar in einer einzigen URL.
Zur Erinnerung: die Operatoren auf einen Blick – __gte / __gt / __lte / __lt für Vergleiche, __not für Ausschlüsse, __in für Mehrfachauswahl und __contains für spaltengenaue Teilstring-Suche. Wer schon einmal mit SQL oder einer anderen Abfragesprache gearbeitet hat, kennt diese Konzepte bereits.
Probiere die Query-Parameter direkt aus
Erstelle ein Dataset aus deiner Excel- oder CSV-Datei und teste Filter, Suche und Pagination mit Postman oder curl – kostenlos.
Jetzt kostenlos starten →