Best Practices

Weniger Anfragen, schnellere Abgleiche, kein 429. Sechs Gewohnheiten, die am meisten sparen, jeweils mit Beispiel zum Kopieren.

Große Seiten abrufen

Ohne limit liefert eine Liste nur 15 Ergebnisse pro Seite, eine lange Liste braucht also viele Anfragen.

Stattdessen so: limit=200 senden, das Maximum. Ein Wert ab 201 wird mit 422 abgelehnt.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/attendances?limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

import requests
headers = {"Authorization": "Bearer {token}", "Accept": "application/json"}
r = requests.get("https://www.zep-online.de/zepinstanz/next/api/v1/attendances", params={"limit": 200}, headers=headers)

const headers = { Authorization: "Bearer {token}", Accept: "application/json" };
const r = await fetch("https://www.zep-online.de/zepinstanz/next/api/v1/attendances?limit=200", { headers });

Spart rund 93 % der Anfragen bei einer langen Liste (1 statt 14 für 200 Einträge).

Nur Änderungen abrufen

Wer bei jedem Lauf alles neu lädt, holt Daten, die sich nicht geändert haben.

Stattdessen so: den größten empfangenen modified-Wert merken und beim nächsten Lauf als modified_after senden (Wasserzeichen).

Diese Endpunkte akzeptieren modified_after: /absences, /attendances, /categories, /customers, /employees, /folders, /invoices, /plannings, /projects, /projects/{id}/tasks, /receipts, /receipts-amounts, /resource-plannings, /tickets, /workhour-balances.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/attendances?modified_after=2026-10-27T15:57:15.000000Z&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

import requests
headers = {"Authorization": "Bearer {token}", "Accept": "application/json"}
watermark = "2026-10-27T15:57:15.000000Z"  # from your last run
url, params, newest = "https://www.zep-online.de/zepinstanz/next/api/v1/attendances", {"modified_after": watermark, "limit": 200}, watermark
while url:  # all pages first, the order is not sorted by modified
    body = requests.get(url, params=params, headers=headers).json()
    newest = max([newest] + [row["modified"] for row in body["data"]])
    url, params = body["links"]["next"], None  # the next link keeps the filters
watermark = newest  # store it only now, for the next run

const headers = { Authorization: "Bearer {token}", Accept: "application/json" };
let watermark = "2026-10-27T15:57:15.000000Z"; // from your last run
let url = `https://www.zep-online.de/zepinstanz/next/api/v1/attendances?modified_after=${watermark}&limit=200`;
let newest = watermark;
while (url) { // all pages first, the order is not sorted by modified
  const body = await (await fetch(url, { headers })).json();
  for (const row of body.data) if (row.modified > newest) newest = row.modified;
  url = body.links.next; // the next link keeps the filters
}
watermark = newest; // store it only now, for the next run

Bei /attendances ist der Cursor inklusiv: Datensätze mit genau dem gesendeten modified-Wert kommen erneut zurück, so geht keiner verloren. Ihr Code muss das Duplikat ignorieren. Teilen sich viele Datensätze einen Zeitstempel, setzen Sie mit id_after hinter der zuletzt verarbeiteten ID fort. Alle anderen Endpunkte liefern nur Datensätze, die strikt nach dem Wert geändert wurden. Die Liste ist nicht nach modified sortiert: alle Seiten lesen und das Maximum nehmen; das Wasserzeichen erst nach der letzten Seite speichern. Ausnahme: Bei /plannings verliert der Next-Link vorerst modified_after und limit, folgen Sie ihm dort nicht, sondern senden Sie page selbst und wiederholen Sie die Filter.

Spart rund das gesamte Datenvolumen unveränderter Datensätze, sobald die erste Komplettladung durch ist.

Datumsbereich eingrenzen

Ein Bereich wie 2000 bis 2026 lässt den Server Jahre an Daten lesen und senden, die Sie nicht brauchen.

Stattdessen so: start_date und end_date (YYYY-MM-DD) für den Zeitraum senden, den Sie wirklich brauchen.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/attendances?start_date=2026-10-01&end_date=2026-10-31&limit=200' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

import requests
headers = {"Authorization": "Bearer {token}", "Accept": "application/json"}
params = {"start_date": "2026-10-01", "end_date": "2026-10-31", "limit": 200}
r = requests.get("https://www.zep-online.de/zepinstanz/next/api/v1/attendances", params=params, headers=headers)

const headers = { Authorization: "Bearer {token}", Accept: "application/json" };
const url = "https://www.zep-online.de/zepinstanz/next/api/v1/attendances?start_date=2026-10-01&end_date=2026-10-31&limit=200";
const r = await fetch(url, { headers });

Spart rund den Anteil der gekürzten Jahre: ein Monat statt 26 Jahre sind etwa 99,7 % weniger Daten.

Rate Limits einhalten

Über den Limits antwortet die API mit 429 und Ihr Abgleich bleibt stehen.

Stattdessen so: Mit X-RateLimit-Remaining das restliche Budget prüfen und bei 429 die Sekunden aus Retry-After abwarten, bevor Sie es erneut versuchen. Limits und Header stehen unter Authentifizierung.

curl -i 'https://www.zep-online.de/zepinstanz/next/api/v1/projects?limit=1' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

import time, requests
headers = {"Authorization": "Bearer {token}", "Accept": "application/json"}
 
def get(url, **kwargs):
    for attempt in range(5):
        r = requests.get(url, headers=headers, **kwargs)
        if r.status_code != 429:
            return r
        time.sleep(int(r.headers.get("Retry-After", 5)))  # wait as told, then retry
    r.raise_for_status()
 
r = get("https://www.zep-online.de/zepinstanz/next/api/v1/projects", params={"limit": 200})

const headers = { Authorization: "Bearer {token}", Accept: "application/json" };
 
async function get(url) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const r = await fetch(url, { headers });
    if (r.status !== 429) return r;
    const wait = Number(r.headers.get("Retry-After") ?? 5);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000)); // wait as told, then retry
  }
  throw new Error("still rate limited");
}
 
const r = await get("https://www.zep-online.de/zepinstanz/next/api/v1/projects?limit=200");

Spart rund jeden Wiederholversuch, der ohnehin abgelehnt würde: einmal warten ist billiger als Dauerfeuer.

Flach filtern statt über Eltern-Objekte zu laufen

Eine Anfrage pro Projekt oder Mitarbeiter vervielfacht Ihre Anfragezahl um die Zahl der Eltern-Objekte.

Stattdessen so: den Listen-Endpunkt einmal abfragen und nach der Eltern-ID filtern, zum Beispiel project_id.

curl 'https://www.zep-online.de/zepinstanz/next/api/v1/attendances?project_id=2' -H 'Authorization: Bearer {token}' -H 'Accept: application/json'

Spart rund eine Anfrage je Eltern-Objekt, über das Sie nicht mehr laufen.

Generierte Clients

Den HTTP-Code müssen Sie nicht selbst schreiben: Erzeugen Sie einen Client aus der OpenAPI-Spezifikation. Unsere CI erzeugt und kompiliert bei jeder Änderung einen Java-Client aus der Spezifikation.

Filtern der Ergebnisse OpenAPI-Spezifikation