Paginierung

Alle Endpunkte, die Listen zurückgeben, unterstützen Paginierung, um Performance und Nutzererlebnis zu verbessern. Diese API verwendet Limit/Offset-Paginierung, eine weit verbreitete Methode, um grosse Datenmengen in handhabbaren Portionen abzurufen.

Parameters

`limit` (optional, default: 10)

Gibt an, wie viele Objekte pro Seite zurückgegeben werden. Muss zwischen 1 und 100 liegen.

Example: limit=25

`offset` (optional, default: 0)

Gibt an, wie viele Datensätze übersprungen werden, bevor Ergebnisse zurückgegeben werden. Dient zur Navigation zu bestimmten Seiten.

Example: offset=50 (skips the first 50 records)

`page` (optional, alternative to offset)

Seitennummer für eine einfachere Navigation. Wenn angegeben, wird das Offset automatisch als (page - 1) × limit berechnet.

Example: page=3 with limit=10 is equivalent to offset=20

Request Examples

# Get first 10 items (default)
curl -X GET "https://app.newtrition-data.com/api/v1/search?query=Brot"

# Get 25 items starting from the beginning

curl -X GET "https://app.newtrition-data.com/api/v1/search?query=Brot?limit=25"

# Get page 3 with 10 items per page (items 21-30)

curl -X GET "https://app.newtrition-data.com/api/v1/search?query=Brot?page=3&limit=10"

# Get 15 items starting from the 45th record

curl -X GET "https://app.newtrition-data.com/api/v1/search?query=Brot?limit=15&offset=45"

Response Format

{
  "data": [
    {
      "id": "item_123",
      "name": "Example Item"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 20,
    "page": 3,
    "total_count": 150,
    "total_pages": 15,
    "has_next": true,
    "has_previous": true
  },
  "links": {
    "self": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=3&limit=10",
    "first": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=1&limit=10",
    "last": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=15&limit=10",
    "next": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=4&limit=10",
    "previous": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=2&limit=10"
  }
}

Response Fields

`data` (array)

Ein Array mit den eigentlichen Antwort-Elementen für die aktuelle Seite.

`pagination` (object)

Enthält Metadaten zum aktuellen Paginierungszustand:

limit (number): Anzahl der angefragten Elemente pro Seite
offset (number): Anzahl der übersprungenen Elemente
page (number): Aktuelle Seitennummer
total_count (number): Gesamtanzahl verfügbarer Elemente
total_pages (number): Gesamtanzahl verfügbarer Seiten
has_next (boolean): Ob es Seiten nach der aktuellen gibt
has_previous (boolean): Ob es Seiten vor der aktuellen gibt

`links` (object)

Vorgefertigte URLs für einfache Navigation:

self: URL der aktuellen Seite
first: URL der ersten Seite
last: URL der letzten Seite
next: URL der nächsten Seite (null auf der letzten Seite)
previous: URL der vorherigen Seite (null auf der ersten Seite)

Search Endpoint Caveat

Bei GET /api/v1/search und GET /api/v2/search werden Ergebnisse gruppiert, um nahezu doppelte Treffer zu reduzieren. Dadurch sollten Metadaten für tiefe Paginierung als Navigationshilfe verstanden werden und nicht als exakte Garantie für eine Seitenanzahl.

pagination.total_count kann bei tiefen Seiten nur ungefähr sein
pagination.total_pages kann bei tiefen Seiten nur ungefähr sein
links.last sollte nicht genutzt werden, um eine exakte letzte Seite für Suchergebnisse vorab zu berechnen

Für Such-Clients bevorzugen Sie sequentielle Navigation mit links.next und links.previous. Bei flacher Paginierung sind die Metadaten weiterhin nützlich, Clients sollten aber nicht davon ausgehen, dass sehr tiefe Suchseiten exakte “letzte Seite”-Semantik besitzen.

Best Practices

For API Consumers

Immer ein Limit angeben, um konsistente Ergebnisse zu erhalten und nicht von Default-Werten abzuhängen
Die mitgelieferten Links in der Antwort zur Navigation nutzen, statt URLs manuell zu bauen
Bei Search-Endpunkten sequentiell navigieren mit next / previous statt auf eine exakte letzte Seite zu vertrauen
Edge Cases behandeln, z. B. leere Seiten oder wenn has_next false ist
Paginierungs-Metadaten vorsichtig cachen; bei Search-Endpunkten sind tiefe Seitenzahlen am besten als ungefähr zu behandeln

Error Handling

Wenn Paginierungsparameter ungültig sind, liefert die API passende Fehlerantworten:

{
  "code": "INVALID_PAGINATION",
  "message": "Limit must be between 1 and 100",
  "details": {
    "parameter": "limit",
    "provided_value": 150,
    "valid_range": "1-100"
  }
}

Performance Considerations

Limit-Grösse: Grössere Seiten reduzieren die Anzahl der Requests, erhöhen aber Response-Zeit und Speicherbedarf
Tiefe Paginierung: Sehr hohe Offset-Werte können langsamere Antworten verursachen
Sortierung: Paginierte Ergebnisse sind konsistent sortiert.