このセクションについて
エンドポイントのリファレンスは契約から生成している
下のエンドポイントのページは tessera の openapi.json から生成しています。なので英語で、バックエンドに合わせて変わります。契約自体も生成物で、コミットされたものと生成結果が違えば CI が失敗するので、コードから遅れることはありません。
契約を取得する
サーバーは条件なしで /openapi.json に契約を公開しています。何も有効にする必要はありません。クライアントを生成するならここを指定します。
curl http://localhost:12923/openapi.jsonfeatures.docs は別のものです。/docs に閲覧用の UI を置くかどうかだけを決め、デフォルトはオフです。オフにしても契約は隠れません。
その UI の画面は CDN から読み込む
features.docs が有効だと、/docs の JavaScript はブラウザが外部の CDN から取得します。
完全にオフラインのインスタンスでは空白のページになります。
認証
三種類あり、各エンドポイントのページに表示されています。
| 方式 | 送り方 |
|---|---|
| session | POST /api/v1/auth/login が設定する tessera_session Cookie。HttpOnly なので、ページのスクリプトからは読むことも設定することもできない |
| bearer | アカウントページか POST /api/v1/tokens で発行する tsk_ で始まるトークンを Authorization: Bearer で送る |
| なし | 公開エンドポイント。features.anonymous_upload が有効なあいだはアップロードもこれに入る |
トークンにできること
トークンは自分の権限を持ち、実際に効くのはトークンと持ち主の権限の共通部分です。持ち主を降格すると、その人のトークンもすべて同時に狭まります。
作るときに permissions を省略すると、shares:create だけになります。「アカウントにできることすべて」ではありません。トークンはアップロードのためにあり、アカウント全体をデフォルトにすると、スクリーンショットツールやバックアップスクリプトのどれもが持ち主のものをすべて消せてしまうからです。
呼び出し元が持っていない権限を求めると、403 で断られます。
API トークンは一度しか表示されない
作ったときに一度返し、あとはダイジェストだけを残します。なくしたら、 取り消して新しく発行するしかありません。
ここにないもの
/s/<コード>/raw と /s/<コード>/download は契約に入っていません。これらは API ではなくリンクの行き先で、形を変えることはできません。チャットに貼られ、印刷され、curl に渡されるからです。使い方は共有を見てください。