Zurück zum Hilfecenter

Schnittstelle: Leitfäden

Blättern, filtern und sauber synchronisieren

Cursor statt Seitenzahlen, `updated_since` statt Vollabgleich.

Für wen

Entwicklerinnen und Entwickler.

Voraussetzungen

Bestehender Zugang mit Leserecht

Schritt für Schritt

  1. 1

    Seitengröße wählen

    `limit` steuert die Anzahl je Seite, erlaubt sind 1 bis 200, Standard ist 50. Größere Seiten sparen Aufrufe, kleinere Seiten antworten schneller.

  2. 2

    Mit dem Cursor blättern

    Die Antwort enthält `page.next`. Diesen Wert unverändert als Parameter `page` der nächsten Anfrage mitgeben. Ist `page.next` gleich `null`, sind Sie am Ende.

    JavaScript
    const key = process.env.ELYPH_API_KEY;

async function fetchAll(resource, params = {}) {
  const rows = [];
  let page = null;
  do {
    const query = new URLSearchParams({ ...params, limit: "200", ...(page ? { page } : {}) });
    const response = await fetch(`https://api.elyph.io/v1/${resource}?${query}`, {
      headers: { Authorization: `Bearer ${key}` },
    });
    if (response.status === 429) {
      const wait = Number(response.headers.get("retry-after") ?? 5);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
    const payload = await response.json();
    rows.push(...payload.data);
    page = payload.page.next;
  } while (page);
  return rows;
}

const actions = await fetchAll("actions", { status: "open" });
console.log(actions.length);
  3. 3

    Nur Änderungen holen

    Merken Sie sich nach jedem Lauf den höchsten `updated_at`-Wert und übergeben Sie ihn beim nächsten Lauf als `updated_since`. Ziehen Sie eine Minute Sicherheitsabstand ab.

    curl
    curl -sS "https://api.elyph.io/v1/actions?updated_since=2026-02-01T03%3A00%3A00Z&limit=200" \
  -H "Authorization: Bearer $ELYPH_API_KEY"
  4. 4

    Doppelte vermeiden

    Verknüpfen Sie Ihre Datensätze über die fachliche Kennung (`reference` bzw. `id`) und schreiben Sie mit „einfügen oder aktualisieren“, nicht mit „immer einfügen“.

API-Konsole

Anfrage zusammenstellen, Code kopieren und — angemeldet und mit eigenem Schlüssel — wirklich ausführen. Die Konsole führt ausschließlich lesende Aufrufe aus.

GET https://api.elyph.io/v1/actions?limit=10

Statuswert exakt wie im Feld `status`.

Nur Objekte mit Termin bis einschließlich diesem Datum.

Kennung des Standorts (UUID der Organisationseinheit).

Nur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601). Grundlage jeder Synchronisation.

Anzahl der Objekte je Seite, 1 bis 200. Standard 50.

Fortsetzungsmarke aus `page.next` der vorherigen Antwort. Keine Seitenzahl.

curl
curl -sS "https://api.elyph.io/v1/actions?limit=10" \
  -H "Authorization: Bearer $ELYPH_API_KEY"

Echttest

Nach der Anmeldung führen Sie dieselbe Anfrage hier mit Ihrem eigenen Schlüssel aus. So sieht eine echte Antwort aus:

Beispielantwort
{
  "data": [
    {
      "reference": "MAS-2026-233",
      "title": "Zweihandschaltung instand setzen",
      "type": "technisch",
      "status": "in_progress",
      "priority": "hoch",
      "due_date": "2026-02-14",
      "owner": {
        "name": "Marco List",
        "email": "marco.list@example.com"
      },
      "site": {
        "reference": "WN",
        "name": "Werk Nord"
      },
      "origin": {
        "type": "assessment",
        "reference": "GBU-2026-014"
      },
      "effectiveness_check": {
        "required": true,
        "done": false,
        "result": null,
        "due_at": "2026-03-15"
      },
      "implemented_at": null,
      "completed_at": null,
      "updated_at": "2026-01-21T11:05:00Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 10
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

Ergebnis

Ein Abgleich, der auch bei zehntausenden Datensätzen stabil und sparsam läuft.

Häufige Stolpersteine

  • Seitenzahlen erwarten: Die Schnittstelle blättert ausschließlich per Cursor; ein Cursor gilt nur für dieselbe Filterkombination.
  • Cursor verändern oder dekodieren: Er ist ein undurchsichtiger Wert und kann sich jederzeit ändern.
  • Filter zwischen zwei Seiten wechseln: Beginnen Sie in diesem Fall neu ohne `page`.

Hintergrund

Der Cursor enthält den Sortierwert und die Kennung des letzten Objekts. Dadurch bleiben Ergebnisse auch dann vollständig, wenn während des Blätterns Datensätze hinzukommen.

Verwandte Artikel