Paginierung | NueForm Docs

Alle Endpunkte der NueForm-API, die Ressourcenlisten zurückgeben, unterstützen seitenbasierte Paginierung. Diese Anleitung behandelt die Query-Parameter, das Antwortformat und Muster, um alle Ergebnisse zu durchlaufen.

Query-Parameter

Steuere die Paginierung über zwei Query-Parameter:

Parameter	Typ	Standard	Beschreibung
`page`	integer	`1`	Die abzurufende Seitennummer (beginnend bei 1).
`per_page`	integer	`20`	Die Anzahl der Einträge pro Seite. Minimum: `1`, Maximum: `100`.

Wenn per_page größer als 100 ist, begrenzt die API den Wert automatisch auf 100. Werte kleiner als 1 werden auf 1 gesetzt.

Beispielanfrage

GET/api/v1/forms?page=2&per_page=25

curl

curl -X GET "https://app.nueform.com/api/v1/forms?page=2&per_page=25" \
  -H "Authorization: Bearer nf_your_api_key_here"

Antwortformat

Paginierte Antworten enthalten neben dem data-Array ein meta-Objekt:

json

{
  "data": [
    {
      "id": "clx1abc2d3e4f5g6h7i8j9k0",
      "title": "Customer Feedback",
      "status": "published",
      "created_at": "2026-01-15T09:30:00.000Z"
    },
    {
      "id": "clx2def3g4h5i6j7k8l9m0n1",
      "title": "Employee Survey",
      "status": "draft",
      "created_at": "2026-01-20T14:00:00.000Z"
    }
  ],
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 73,
    "total_pages": 3
  }
}

Meta-Felder

Feld	Typ	Beschreibung
`page`	integer	Die aktuelle Seitennummer.
`per_page`	integer	Die Anzahl der Einträge pro Seite (wie tatsächlich angewendet).
`total`	integer	Die Gesamtzahl der Einträge über alle Seiten hinweg.
`total_pages`	integer	Die Gesamtzahl der Seiten (berechnet als `ceil(total / per_page)`).

Alle Seiten durchlaufen

Wenn du alle Einträge eines Listen-Endpunkts abrufen möchtest, iteriere über die Seiten, bis page größer als total_pages ist.

JavaScript

javascript

async function fetchAllForms() {
  const allForms = [];
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://app.nueform.com/api/v1/forms?page=${page}&per_page=100`,
      {
        headers: {
          "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
        },
      }
    );

    const { data, meta } = await response.json();
    allForms.push(...data);
    totalPages = meta.total_pages;
    page++;
  } while (page <= totalPages);

  console.log(`Fetched ${allForms.length} forms in total.`);
  return allForms;
}

Python

python

import os
import requests

API_KEY = os.environ["NUEFORM_API_KEY"]
BASE_URL = "https://app.nueform.com/api/v1"

def fetch_all_forms():
    all_forms = []
    page = 1
    total_pages = 1

    while page <= total_pages:
        response = requests.get(
            f"{BASE_URL}/forms",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"page": page, "per_page": 100},
        )
        body = response.json()
        all_forms.extend(body["data"])
        total_pages = body["meta"]["total_pages"]
        page += 1

    print(f"Fetched {len(all_forms)} forms in total.")
    return all_forms

Async Generator (JavaScript)

Nutze bei großen Datenmengen einen Async Generator, um Einträge direkt bei Eintreffen zu verarbeiten, statt alles in den Speicher zu laden:

javascript

async function* paginatedForms(perPage = 100) {
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://app.nueform.com/api/v1/forms?page=${page}&per_page=${perPage}`,
      {
        headers: {
          "Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
        },
      }
    );

    const { data, meta } = await response.json();
    totalPages = meta.total_pages;

    for (const form of data) {
      yield form;
    }

    page++;
  } while (page <= totalPages);
}

// Usage
for await (const form of paginatedForms()) {
  console.log(`Processing: ${form.title}`);
}

Sonderfälle

Leere Ergebnisse

Wenn keine Einträge zur Anfrage passen, gibt die API ein leeres data-Array mit total: 0 zurück:

json

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 0,
    "total_pages": 0
  }
}

Seite jenseits des Endes

Die Anfrage einer Seitennummer über total_pages hinaus liefert ein leeres data-Array. Die meta-Werte spiegeln weiterhin die gesamte Sammlung wider:

json

{
  "data": [],
  "meta": {
    "page": 10,
    "per_page": 20,
    "total": 73,
    "total_pages": 4
  }
}

Ungültige Parameter

Ungültige Paginierungs-Parameter werden tolerant behandelt:

Eingabe	Verhalten
`page=0` oder `page=-1`	Fällt auf `1` zurück
`page=abc`	Fällt auf `1` zurück
`per_page=0` oder `per_page=-5`	Fällt auf `1` zurück
`per_page=500`	Wird auf `100` begrenzt
`per_page=abc`	Fällt auf `20` zurück

Best Practices

Nutze das maximale `per_page` für Massenabrufe

Wenn du alle Ressourcen abrufst, setze per_page=100, um die Anzahl der API-Aufrufe zu minimieren. Jeder Aufruf zählt gegen dein Rate Limit.

Prüfe `total_pages` vor dem Iterieren

Lies immer total_pages aus dem meta-Objekt, um zu wissen, wann du aufhören musst. Iteriere nicht endlos und gehe nicht von einer festen Seitenzahl aus.

Baue bei großen Datenmengen eine Pause zwischen den Seiten ein

Wenn du viele Seiten abrufst, füge eine kleine Verzögerung zwischen den Anfragen ein, um nicht ans Rate Limit zu stoßen:

javascript

// Add a 200ms delay between page requests
await new Promise((resolve) => setTimeout(resolve, 200));

Cache die Gesamtzahl, wenn es passt

Wenn du nur die Gesamtzahl brauchst (z. B. um „47 Formulare" anzuzeigen), fordere per_page=1 an und lies meta.total, um die Datenmenge zu minimieren:

curl

curl -X GET "https://app.nueform.com/api/v1/forms?per_page=1" \
  -H "Authorization: Bearer nf_your_api_key_here"

Paginierte Ergebnisse spiegeln den Datenstand zum Zeitpunkt der jeweiligen Anfrage wider. Werden zwischen den Seitenabrufen Einträge erstellt oder gelöscht, kann es zu Duplikaten oder fehlenden Einträgen kommen. Für konsistente Snapshots rufe alle Seiten zügig ab oder nutze Webhooks für Echtzeit-Updates.