REZICSへ

開発者

本を「読了」にする操作も、API で。

ライブラリで作品を「読了」にすると、ウェブサイトは次のリクエストを送ります。プログラムから同じリクエストを送ると、同じ確認を経て同じ結果を得られます。

書き込み

書き込みリクエストを1行ずつ見る

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"
}
バージョン番号、日付、冪等性キーは例です。

  • パスは作品を指定

    {id}

    REZICS のすべての項目に https://rezics.com/id/ から始まる固定識別子があります。言語やサイトが変わっても同じ識別子です。

  • プロフィールを指定

    actingSubject

    アカウントは個人または組織を代表できます。各書き込みで、どのプロフィールとして操作するかを指定します。サーバーは実行前にその権限を確認します。

  • 安全に再送

    Idempotency-Key

    書き込みごとに冪等性キーを付けます。タイムアウトや切断の後に同じキーで再送しても、処理は重複しません。

  • 上書きを防止

    expectedVersion

    3番目のバージョンを読み込んだら、その番号を指定します。その間に他の人が変更していた場合、今回の書き込みは上書きしません。

  • エラーの詳細を返す

    application/problem+json

    失敗時の code は固定です。プログラムはメッセージ文を比較せず、コードに基づいて分岐できます。

再送

同じリクエストを再送すると、同じ結果が返ります。

同じキーと内容で再送すると、サーバーは最初の結果を返します。バージョンは4のままで、replayed が true になります。同じキーで内容を変えると 409 reader_status_conflict を返します。バージョンが3でなくなっていた場合は 409 stale_reader_status を返すため、再読み込みしてから書き込みます。

  • 初回

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

  • 再送

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

  • バージョンが古い

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

型

API と型は、同じ定義から。

REZICS のウェブサイトは TypeScript で API を呼び出し、リクエストとレスポンスの型はサーバーのルート定義から直接取得します。フィールド名の変更やエラーコードの追加は、呼び出し側でコンパイル時に検出できます。TypeScript SDK も同じ定義から生成するため、ウェブサイトと同じ型を利用できます。

OpenAPI 3.1 のドキュメントも同じルート定義から生成されます。各操作の認証方法、リクエスト形式、ステータスコードごとのレスポンスを記載します。

main().v1
  .works({ id: uuid(work) })
  ['reader-status'].put({
    actingSubject,
    expectedVersion,
    status: 'read',
    ...dates,
  }, headers())
REZICS ウェブサイトのライブラリ機能から抜粋。

generated/openapi/main/public.json

読み取り

読み取りにもルールがあります。

  • nextCursor · snapshot

    長いリストには次ページのカーソルを付け、最後まで順に読み取れます。ライブラリのエクスポートにはスナップショットを添えます。途中でデータが変わった場合は明記し、寄せ集めのファイルを渡しません。

  • count.precision

    検索結果の合計件数が正確な値か、「少なくともこの数」かを明記します。

  • title.language · basis

    タイトルには言語タグと表記方向を付け、その言語が指定されたものか、同じ文字体系か、別の文字体系か、代替なのかを示します。

  • 404 resource_unavailable

    閲覧権限のないリソースには、存在しない場合と同じレスポンスを返し、存在を明かしません。

開発者

その他のページ

同じ API で、自分のツールを開発。

自分のプログラムから作品、ライブラリ、コミュニティの情報を読み書きできます。すべての操作に REZICS のプロフィールと認可ルールを適用します。

REZICSへ

プロダクト

モジュール

言語