Paginierung und Sortierung

Paginierung

Alle API-Endpunkte, die eine Ressource auflisten (zum Beispiel Alle Benutzer auflisten), geben paginierte Ergebnisse in folgender Struktur zurück:

{
  "count": 42,
  "next": "https://api.schulungstool.de/v1/users/?page=3",
  "previous": "https://api.schulungstool.de/v1/users/?page=1",
  "results": ["..."]
}

Schlüssel	Wert
`count`	integer – Gesamtzahl der gefundenen Ergebnisse
`next`	string <url> oder null – URL der nächsten Seite, falls vorhanden
`previous`	string <url> oder null – URL der vorherigen Seite, falls vorhanden
`results`	array <Objekt> – die Objekte der aktuellen Seite

Mit dem Query-Parameter page legen Sie fest, welche Seite zurückgegeben wird. Standardmäßig ist das die erste Seite (page=1). Die dritte Seite rufen Sie zum Beispiel mit ?page=3 ab.

Seitengröße

Standardmäßig enthält eine Seite höchstens 25 Ergebnisse. Mit dem Query-Parameter page_size wählen Sie eine andere Seitengröße zwischen 1 und 100, zum Beispiel ?page_size=100 für 100 Ergebnisse pro Seite. Die URLs in next und previous behalten die gewählte Seitengröße bei.

Werte außerhalb dieses Bereichs, und Werte, die keine ganze Zahl sind, beantwortet die API mit einem Validierungsfehler, der page_size in field_errors nennt.

Sortierung

Bei der Auflistung einer Ressource können Sie die Sortierreihenfolge der Ergebnisse beeinflussen: Legen Sie mit dem Query-Parameter ordering ein Feld oder mehrere Felder (kommagetrennt) fest, nach denen sortiert wird.

Die Ergebnisse können aufsteigend (ordering=Feldname) und absteigend (ordering=-Feldname) sortiert werden, indem dem Feldnamen ein - vorangestellt wird.

Beispiele:

Kurse nach Namen sortieren:
- ordering=name: aufsteigend nach Namen
- ordering=-name: absteigend nach Namen
Kursteilnahmen nach Fälligkeitsdatum und Kursnamen sortieren:
- ordering=due_date,course: aufsteigend nach Fälligkeitsdatum, dann aufsteigend nach Kursnamen
- ordering=-due_date,course: absteigend nach Fälligkeitsdatum, dann aufsteigend nach Kursnamen

Welche Felder je Endpunkt sortierbar sind, zeigt der Parameter ordering des jeweiligen Endpunkts in der API-Referenz.