Paginierung

Zwei Parameter

Jede Liste nimmt dieselben zwei Query-Parameter, einmal in der Spezifikation deklariert und von jeder Operation geteilt. Alles außerhalb der Grenzen ist ein 400 mit INVALID_PARAMETER; ein unbekannter Parameter wird ignoriert, nicht abgelehnt.

per_page endet fast überall bei 100. Eine größere Obergrenze (1000, 500, 50) gilt für die Bulk-Listen: /v1/firearms/media, /v1/contract/findings, /v1/data/tasks, /v1/updates.

6 Operationen sind Ranglisten statt Listen: sie nehmen ein einzelnes limit, liefern die obersten Zeilen und tragen kein pagination-Objekt: /v1/firearms/top, /v1/popular/firearms, /v1/stats/calibers/popular, /v1/stats/manufacturers/prolific, /v1/stats/feature-frequency, /v1/docs/guides/search.

Die Hülle

Eine paginierte Antwort verpackt die Seite jedes Mal im selben Objekt. Das Beispiel unten ist aus den Beispielen des Schemas gebaut und kann daher nicht von dem abweichen, was die API sendet.

1{2  "success": true,3  "data": [4    /* one page of records */5  ],6  "pagination": {7    "page": 1,8    "per_page": 20,9    "limit": 20,10    "total": 42,11    "totalPages": 312  }13}

• pagination.pageintegererforderlich

  The page this response is, 1-based.

• pagination.per_pageintegererforderlich

  Page size. Same value as limit.

• pagination.limitintegererforderlich

  Page size. Alias of per_page.

• pagination.totalintegeroptional

  Total records matching the query across every page.

• pagination.totalPagesintegeroptional

  How many pages the result set spans at the current per_page.

Page-size is reported under both per_page (matching the request parameter) and limit (retained for existing integrations). They always carry the same value. total and totalPages are omitted for Explorer and anonymous callers.

Eine Liste durchlaufen

Die Schleife, die auf jedem Tarif funktioniert, steuert sich über die gerade empfangene Seite, nicht über totalPages. Vier Regeln und der Code in drei Sprachen.

flowchart LR
  first["GET the list<br/>with the largest per_page"] --> rows["Read data[]"]
  rows --> short{"Fewer rows<br/>than per_page?"}
  short -->|"yes"| done["That was the last page"]:::ok
  short -->|"no"| deeper{"Next page within<br/>your plan's depth?"}
  deeper -->|"yes"| nextPage["GET page + 1"]
  nextPage --> rows
  deeper -->|"no"| refuse["Refused: 403 PAGINATION_DEPTH_EXCEEDED<br/>filter the list, or upgrade"]:::fail
  totals["total / totalPages"] -.->|"absent on some plans"| trap["Never loop on these"]:::fail

1. 1Aufhören, wenn eine Seite zu kurz zurückkommt. Weniger Zeilen als per_page bedeutet auf jedem Tarif: letzte Seite.
2. 2total und totalPages als optionale Extras behandeln. Bei Explorer- und anonymen Aufrufen fehlen sie, sodass eine Schleife mit page < totalPages dort nach einer Seite stoppt.
3. 3Die größte nutzbare Seite anfordern. per_page=100 bedeutet 100× weniger Anfragen gegen Minutenlimit und Tageskontingent und erreicht dieselben Zeilen.
4. 4Einmal durchlaufen, dann anders aktuell bleiben. Jede Seite trägt ein ETag und antwortet mit 304, wenn unverändert, und Daten-Webhooks pushen Katalogänderungen, sodass ein Spiegel die Liste nie erneut durchläuft. Mehr als 10 aufeinanderfolgende Seiten innerhalb von 90 Sekunden werden abgelehnt.

1# Page 1, then keep going while a page comes back full2curl -H "X-API-Key: your_api_key" \3  "https://api.gunspec.io/v1/firearms?category=rifle&per_page=100&page=1"4 5curl -H "X-API-Key: your_api_key" \6  "https://api.gunspec.io/v1/firearms?category=rifle&per_page=100&page=2"

Was jeder Tarif lesen darf

Bei der Paginierung unterscheiden sich die Tarife am stärksten, und jede Regel unten wird von der API durchgesetzt, nicht per Konvention. Die Zahlen stammen aus derselben Konfiguration, die die Middleware liest.

Wie eine abgelehnte Seitenanfrage aussieht

• 403PAGINATION_DEPTH_EXCEEDED

  The plan does not page this deep into a list. Narrow the list with filters, or upgrade for deeper paging.

• 429PAGINATION_BURST

  Too many sequential pages in a short time. Slow the walk down, or use a larger per_page.

Tarife vergleichenAlle Katalogschutzmaßnahmen

Sortierung

Wo eine Liste sortiert werden kann, deklariert sie ein sort-Vokabular und eine order-Richtung; die Standardreihenfolge zeigt die Referenz je Operation. Jede andere Liste hat eine feste Reihenfolge, die die Beschreibung der Operation nennt.

• /v1/firearms
  • name
  • weight
  • year
  • caliber
  • created_at
  • favorites

  order: asc | desc

• /v1/me/support
  • created_at
  • updated_at
  • status
  • priority

  order: asc | desc

Jede Operation, die paginiert

41 Operationen nehmen page und per_page und antworten mit der Hülle; 6 nehmen ein einzelnes limit. Jede Zeile verlinkt auf ihre Referenzseite.

SDKs und Agenten

Die offiziellen SDKs bieten einen Auto-Paging-Iterator, der jede Regel dieser Seite anwendet: Seiten werden bei Bedarf geholt, bei einer kurzen Seite stoppt er und totalPages liest er nie.

1for await (const firearm of client.firearms.listAutoPaging({ category: 'rifle' })) {2  console.log(firearm.name); // pages are fetched on demand3}

1for firearm in client.firearms.list_auto_paging({"category": "rifle"}):2    print(firearm["name"])  # pages are fetched on demand

SDK-ReferenzDoku für KI-Agentenllms.txt

Sie geben das an einen Coding-Agenten? Die Agenten-Pakete und llms.txt enthalten dieselben Regeln in einer Form, auf die ein Modell reagieren kann: über das Kurzseiten-Signal blättern, per_page ausreizen und bei 403 oder 429 error.reason lesen, bevor erneut versucht wird.