Zu REZICS

Entwickler

Ein Buch als gelesen markieren: ein API-Vorgang.

Wenn du ein Werk in deiner Bibliothek als „Gelesen“ markierst, sendet die Website die folgende Anfrage. Dein Programm sendet dieselbe Anfrage, erhält dasselbe Ergebnis und durchläuft dieselben Prüfungen.

Schreiben

Eine Schreibanfrage, Zeile für Zeile

PUT /v1/works/{id}/reader-status
Authorization: Bearer …
Idempotency-Key: 7f3c2a9e-read
Content-Type: application/json

{
  "actingSubject":
    "https://rezics.com/id/…",
  "expectedVersion": 3,
  "status": "read",
  "finishedOn": "2026-10-19"
}
Versionsnummer, Datum und Idempotenzschlüssel sind Beispiele.

  • Der Pfad verweist auf ein Werk

    {id}

    Jedes Objekt auf REZICS hat eine feste Kennung mit dem Präfix https://rezics.com/id/. Sie bleibt über Sprachen und Websites hinweg gleich.

  • Identität angeben

    actingSubject

    Ein Konto kann für dich oder eine Organisation handeln. Bei jedem Schreibvorgang gibst du die verwendete Identität an. Der Server prüft ihre Berechtigungen vor der Ausführung.

  • Anfragen sicher wiederholen

    Idempotency-Key

    Jeder Schreibvorgang enthält einen Idempotenzschlüssel. Nach einer Zeitüberschreitung oder Verbindungsunterbrechung kannst du dieselbe Anfrage mit demselben Schlüssel wiederholen, ohne doppelt zu schreiben.

  • Überschreiben verhindern

    expectedVersion

    Wenn du Version 3 gelesen hast, gib Version 3 an. Hat jemand inzwischen etwas geändert, überschreibt dein Schreibvorgang die Änderungen nicht.

  • Fehler enthalten Problemdetails

    application/problem+json

    Bei einem Fehler ist der Code festgelegt. Dein Programm kann danach verzweigen, ohne den Meldungstext zu vergleichen.

Wiederholen

Dieselbe Anfrage liefert bei einer Wiederholung dasselbe Ergebnis.

Sendest du dieselbe Anfrage mit demselben Schlüssel erneut, gibt der Server das erste Ergebnis zurück. Die Version bleibt 4 und replayed wird true. Verwendest du denselben Schlüssel mit anderem Inhalt, kommt 409 reader_status_conflict zurück. Ist die Version nicht mehr 3, kommt 409 stale_reader_status zurück. Lies die aktuelle Version und sende die Änderung erneut.

  • Erster Aufruf

    200
{
  "status": "read",
  "version": 4,
  "replayed": false
}

  • Wiederholen

    200
{
  "status": "read",
  "version": 4,
  "replayed": true
}

  • Version veraltet

    409
{
  "status": 409,
  "code":
    "stale_reader_status"
}

Typen

API und Typen aus derselben Definition

Die REZICS-Website ruft die API mit TypeScript auf. Die Typen für Anfragen und Antworten stammen direkt aus den Routendeklarationen des Servers. Ändert sich ein Feldname oder kommt ein Fehlercode hinzu, erfährt es der aufrufende Code schon beim Kompilieren. Das TypeScript-SDK wird aus derselben Definition erstellt und verwendet dieselben Typen wie die Website.

Auch die OpenAPI-3.1-Dokumentation wird aus denselben Routendeklarationen erstellt. Sie beschreibt die Prüfung, das Anfrageformat und die Antwort für jeden Statuscode.

main().v1
  .works({ id: uuid(work) })
  ['reader-status'].put({
    actingSubject,
    expectedVersion,
    status: 'read',
    ...dates,
  }, headers())
Auszug aus der Bibliotheksfunktion der REZICS-Website.

generated/openapi/main/public.json

Lesen

Auch das Lesen folgt festen Regeln

  • nextCursor · snapshot

    Lange Listen enthalten einen Cursor für die nächste Seite und lassen sich bis zum Ende durchgehen. Ein Bibliotheksexport enthält außerdem einen Snapshot. Ändern sich Daten während des Exports, wird das klar angezeigt, statt dir eine unvollständige Datei zu geben.

  • count.precision

    Bei der Gesamtzahl der Suchergebnisse steht dabei, ob sie genau ist oder nur „mindestens“ angibt.

  • title.language · basis

    Titel enthalten eine Sprachkennung und Schreibrichtung. Außerdem steht dabei, ob die Sprache angefragt, in derselben Schrift, in einer anderen Schrift oder als Ersatz gewählt wurde.

  • 404 resource_unavailable

    Für Ressourcen ohne deine Berechtigung sieht die Antwort genauso aus wie für nicht vorhandene Ressourcen. Sie verrät nicht, dass es sie gibt.

Entwickler

Weitere Seiten

Schreibe eigene Werkzeuge mit derselben API.

Lass dein Programm Werke, deine Bibliothek und Community-Daten lesen und schreiben. Jeder Vorgang folgt denselben Identitäts- und Berechtigungsregeln von REZICS.

Zu REZICS

Produkte

Module

Sprache