Konventionen
Paginierung, Datumsangaben, Limits und Antwortheader.
Antwortumschläge
Jede erfolgreiche Antwort hat das Format { "data": ..., "request_id": "..." }. Geben Sie bei einer Problemmeldung die
request_id an. Anhand dieser ID lässt sich der passende Protokolleintrag finden.
Paginierung
Immer cursorbasiert, niemals mit Offset. Übergeben Sie den next_cursor aus der vorherigen Antwort
als cursor.
Bei einem Offset wird auf jeder Seite der gesamte bisherige Bereich erneut durchlaufen. Schlimmer noch: Werden zwischen zwei Anfragen Einträge eingefügt, überspringt die Paginierung Zeilen. Ein Client, der eine gerade bearbeitete Liste seitenweise abruft, übersieht so unbemerkt Einträge. Mit einem Cursor passiert das nicht.
Nachsichtige Eingaben
limit wird angepasst, nicht abgelehnt: Bei einer Anfrage nach 500 erhalten Sie 100, und die Antwort
nennt das angewendete Limit. Ein nicht numerischer Wert für limit führt weiterhin zu einem Fehler,
weil es sich dabei um einen Irrtum und nicht um eine Absicht handelt.
Datumsangaben können als 2026-07-01 oder als vollständiger ISO-8601-Zeitstempel angegeben werden. Ein reines Datum auf der
to-Seite steht für das ENDE dieses Tages. Das entspricht der üblichen Bedeutung von „bis zum
31.“.
Sicher schreiben
Bei jeder Schreiboperation, die etwas ersetzt, können Sie angeben, was ersetzt werden soll. Senden Sie den
expected_hash einer Datei oder eines Eintrags, den Sie gelesen haben. Wurde er inzwischen geändert, wird die Änderung mit
409 conflict abgelehnt. Für die Veröffentlichung, das Zurücksetzen und das Zurückziehen einer Veröffentlichung benötigen Sie den Wert von
expected_generation, den Sie gelesen haben. So ändern Sie nur den Zustand, den Sie geprüft haben. Beide Konfliktantworten enthalten unter error.details die Angaben, die Sie erneut abrufen müssen.
Lang laufende Vorgänge
Ein Build wird sofort mit dem Status queued zurückgegeben. Rufen Sie den Status so lange ab, bis er
ready, failed oder cancelled lautet. Diese Status sind endgültig. Beenden Sie die Abfragen, sobald einer davon erscheint.
Ratenlimits
Es gelten fünf Limits, die unterschiedliche Bereiche schützen: den Durchsatz pro Zugangsdaten, kurze Lastspitzen,
das Volumen pro IP-Adresse, die Clientregistrierung und speziell FEHLGESCHLAGENE
Authentifizierungen. Jede Antwort enthält das verbleibende Kontingent in den Headern. Eine Antwort mit Status 429 enthält Retry-After.