APIの概要

KolleKのAPIは、Webアプリケーションを1対1でそのまま反映したJSON APIです。アプリのあらゆる機能(コレクションの作成、アイテムやコピーの追加、取引の記録、メンバー管理)には、まったく同じルールで動く対応するエンドポイントがあります。ブラウザ上であなたの権限で実行できることは、あなたのトークンでHTTP経由でも実行できます。実行できないことは、APIでもアプリと同じように拒否されます。

このページでは、全体の考え方を説明します。エンドポイントごとの完全かつ常に最新のリファレンスは、コードから自動生成され、お使いのインスタンスから提供されます。

• /docs/api: ブラウザで閲覧できるリファレンス。
• /docs/api.md: リファレンス全体をMarkdown形式でまとめたもの。
• /docs/api/{section}.md: 1つのセクションだけをMarkdown形式でまとめたもの。特定のトピックだけをツールに読み込ませたいときに便利です。

あなたのアカウントに限定される

APIはテナントスコープです。トークンは1人のユーザーに紐づき、そのユーザーは必ず1つのアカウントに所属するため、すべてのリクエストはそのアカウントを通じて処理されます。他のアカウントのデータには到達できず、どこにもアカウントIDを渡す必要はありません。設定すべきことは何もなく、認証さえすれば自分のワークスペースの中にいます。

アプリと同じ権限が適用されます。閲覧者のトークンは読み取りはできても書き込みはできません。編集者のトークンはカタログの内容を管理できます。オーナー限定の操作(メンバー管理、アカウント設定)には、オーナーのトークンが必要です。

リソースの構造

リソースはKolleKの整理方法に沿って入れ子になっています。

• アカウントは、メンバー、コレクションタイプ、カスタムフィールド、タグ、保管場所、コンディションといった、アカウント全体のリソースを保持します。
• コレクションは、カテゴリやセットとともにアイテムを保持します。
• アイテムは写真とコピーを保持します。
• コピーは、取引、評価、保険記録、貸借記録、手入れ記録、来歴イベント、保管場所の履歴、書類、そしてそれらをまとめたタイムラインといった履歴系のリソースを保持します。

レスポンスは、おおむねJSON:APIの形式に沿っています。各リソースは type、id、attributes、links として返されます。一覧はページネーションされ、標準的なエンベロープに包まれます。詳しくは レート制限と規約 を参照してください。

このセクションで扱う内容

このセクションのページでは、始め方と、自動生成されたリファレンスだけでは学べない考え方、つまり認証、規約、そしてWebhookの現状を扱います。特定のエンドポイントとそのパラメータ、リクエストとレスポンスの実例については、/docs/api を直接参照してください。

次に読むページ

• APIで認証する で最初のリクエストを送ってみましょう。
• クライアントを書く前に レート制限と規約 にざっと目を通しておきましょう。
• お使いのインスタンスの /docs/api で、自動生成されたリファレンスを閲覧してみましょう。