Konventionen

Blättern, Fehler, Limits, Idempotenz

Die vier Punkte, die in jeder API anders sind — hier mit Zahlen statt mit Prosa.

Blättern

Jede Liste antwortet mit data und pagination. Geblättert wird über einen Cursor: du schickst die id des letzten Elements der Vorseite als starting_after. Fehlt next_starting_after in der Antwort, ist der Durchgang fertig.

Feld	Bedeutung
starting_after	Die `id` des letzten Elements der Vorseite. Der empfohlene Weg — stabil, auch wenn sich die Liste zwischen zwei Seiten ändert. Eine unbekannte oder gelöschte `id` ergibt 422, keine leere Seite.
next_starting_after	Steht in `pagination`, solange es weitergeht: der Wert für dein nächstes `starting_after`. Fehlt er, bist du am Ende.
limit	Zeilen je Seite. Standard 50, Höchstwert 200 — ein größerer Wert ergibt 422, keine gekürzte Seite.
offset	Zu überspringende Zeilen — für einen einmaligen Blick auf eine bestimmte Seite. Zusammen mit `starting_after` ergibt es 422: zwei Positionsangaben in einer Anfrage haben keine widerspruchsfreie Bedeutung.
include_total	`true` liefert zusätzlich `total`. Nur anfordern, wenn du die Zahl anzeigst.
has_more	Steht in jeder Antwort und sagt, ob eine weitere Seite existiert — kein Raten, keine Extra-Runde.

Warum nicht einfach offset: der beschreibt eine POSITION in der Liste. Kommt zwischen Seite 1 und Seite 2 eine Buchung dazu, rutscht alles um eine Stelle — offset=50 überspringt dann eine Zeile, beim Löschen kommt eine doppelt. In deiner Datenbank fehlt danach eine Buchung, und nichts in der Antwort verrät es. Der Cursor benennt den letzten Datensatz, den du gesehen hast, und kann deshalb nicht verrutschen.

Anfrage

# Erste Seite
curl 'https://open-api.mynextdays.com/v1/reservations?limit=50' \
  -H 'Authorization: Bearer <access_token>'

# Nächste Seite: die ID aus pagination.next_starting_after übernehmen
curl 'https://open-api.mynextdays.com/v1/reservations?limit=50\
&starting_after=d41d8cd9-…' \
  -H 'Authorization: Bearer <access_token>'

Idempotenz

Beim Anlegen einer Buchung ist der Header Idempotency-Key Pflicht. Wähle je Vorgang einen eindeutigen Wert (etwa eine UUID) und wiederhole ihn, wenn du denselben Aufruf erneut sendest. Ohne diesen Schutz erzeugt ein Netzabbruch mit Wiederholung zwei Buchungen — und die zweite sperrt Nächte, die niemand bestellt hat.

Gleicher Schlüssel, gleiche Nutzlast → die erste Antwort kommt wortgleich zurück, mit dem Header Idempotency-Replayed: true.
Gleicher Schlüssel, ANDERE Nutzlast → 422. Für einen neuen Vorgang gehört ein neuer Schlüssel.
Gleicher Schlüssel, erster Aufruf läuft noch → 409. Kurz warten, dann wiederholen; nicht mit neuem Schlüssel nachfassen.

Anfrage

curl -X POST https://open-api.mynextdays.com/v1/reservations \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Idempotency-Key: 8f9a1c30-6b1e-4d2a-9f77-4e0c1b2d3a55' \
  -H 'Content-Type: application/json' \
  -d '{
    "property_id": "8f14e45f-…",
    "check_in": "2026-09-10",
    "check_out": "2026-09-13",
    "total_amount": 4500,
    "currency": "DKK",
    "adults": 2,
    "guest": {
      "first_name": "Jens",
      "last_name": "Hansen",
      "email": "jens@example.dk"
    }
  }'

Nächste SeiteFehler