REST API

開発者優先

REST API は Glossia の背骨です。ダッシュボード、CLI、そしてMCP server はいずれも同じエンドポイントを利用します。機能を実装するとまず API に実装され、そこから他のすべての部分に展開されます。

これは UI によって制限されることを意味しません。CI/CD 統合からカスタムダッシュボードまで、あらゆる作業フローは同じ安定した文書化されたインターフェースの上に構築できます。

認証

Glossia は、すべての API 認証に OAuth 2.1 と PKCE を使用します。このフローはファーストパーティとサードパーティのクライアントの両方をサポートします。認証と権限付与ドキュメントで完全な解説を確認してください。

動的クライアント登録 -- クライアントはリダイレクト URI と付与方法を指定してプログラム的に/oauth/registerに登録します。手動承認ステップはなく、クリック-through なポータルもありません。

PKCE の使用による認証コード -- ユーザーはブラウザの同意画面を通じてクライアントを承認します。PKCE 拡張機能により、 secret を保存できない公開クライアントでもトークンが安全に保たれます。

トークンのライフサイクル -- アクセステークンを交換、クエリ、無効にすることが標準的な OAuth エンドポイントを通じて可能です。トークンエンドポイントのレート制限はブルートフォース攻撃から守ります。

権限付与

アクセス制御は 2 つのレイヤを使用します。認証ドキュメントにスコープ、ロール、および完全な権限マトリックスの詳細が説明されています。

スコープはトークンがアクセスできるリソースのcategoriesを定義します。voice:readを持つトークンは音声の構成を読めるかもしれませんが変更することはできません。スコープはresource:actionパターンに従います：account:read、organization:write、glossary:adminで辞書管理など、その他も同様です。

ポリシーはユーザーと特定のリソース之间的関係をチェックします。正しくスコープを持つ有効なトークンでも、ユーザーが所属していない組織にはアクセスできません。すべてのリクエストは両方のレイヤに対してチェックされます。

ページネーション、フィルタリング、ソート

すべてのリストエンドポイントは一貫したメタデータを含むページネーションされた結果を返します:

すべてのレスポンスにtotal_count、total_pages、current_page、page_size、has_next_page?、およびhas_previous_page?が含まれているため、クライアントは推測なしでページネーションコントロービルを構築できます。

インデックスされたフィールドを指定するfilters[field]=valueクエリパラメータでフィルタします。order_by[]パラメータで昇順または降順でソートします。すべてのリソースでインターフェースは同じです。

OpenAPI とインタラクティブドキュメント

完全な OpenAPI 3.1 仕様が/api/openapi.jsonで利用可能です。インタラクティブ API リファレンスは Scalar で提供され、エンドポイントを探索、スキーマを検査、ブラウザから直接テストリクエストを作成できます。

任意の言語のクライアントライブラリは仕様から生成できます。 thấu約はバージョン化されており安全なので、新機能を実装しても你们的 integration が壊れることはありません。