# APIの概要

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

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

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

:::note
セルフホストのインスタンスでは、このリファレンスは公開マーケティングサイトの一部であり、初期状態ではオフになっています。運用者が `SHOW_MARKETING_SITE` 設定で有効にします。[インスタンスを設定する](https://getkollek.com/ja/docs/serufu-hosutingu/insutansu-no-settei) を参照してください。
:::

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

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

アプリと同じ[権限](https://getkollek.com/ja/docs/kihon-konseputo/akaunto-yuza-to-kengen)が適用されます。閲覧者のトークンは読み取りはできても書き込みはできません。編集者のトークンはカタログの内容を管理できます。オーナー限定の操作(メンバー管理、アカウント設定)には、オーナーのトークンが必要です。

## リソースの構造

リソースは[KolleKの整理方法](https://getkollek.com/ja/docs/kihon-konseputo/kollek-no-shikumi)に沿って入れ子になっています。

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

レスポンスは、おおむねJSON:APIの形式に沿っています。各リソースは `type`、`id`、`attributes`、`links` として返されます。一覧はページネーションされ、標準的なエンベロープに包まれます。詳しくは [レート制限と規約](https://getkollek.com/ja/docs/kaihatsusha-to-api/reto-seigen-to-kiyaku) を参照してください。

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

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

:::note
テストモードはありません。すべてのAPIリクエストは実際のアカウントに対して実行されるため、試しながら破壊的な呼び出しを行う際は注意してください。
:::

## 次に読むページ

- [APIで認証する](https://getkollek.com/ja/docs/kaihatsusha-to-api/api-de-ninshou) で最初のリクエストを送ってみましょう。
- クライアントを書く前に [レート制限と規約](https://getkollek.com/ja/docs/kaihatsusha-to-api/reto-seigen-to-kiyaku) にざっと目を通しておきましょう。
- お使いのインスタンスの `/docs/api` で、自動生成されたリファレンスを閲覧してみましょう。