OpenAPI・APIカタログ

配信APIのHTTP仕様を機械で読めるOpenAPIとして公開しています。APIカタログからは、その定義やドキュメントの参照先を取得できます。どちらもAPIキーなしで読み取れます。

公開URL

OpenAPIはエンドポイント、認証ヘッダー、クエリ、レスポンス、エラーを記述します。APIカタログはAPIの参照先を探すための一覧です。

ツールへ読み込む

OpenAPI 3.1に対応したAPIクライアントやコード生成ツールのインポート機能に、https://api.genko.me/openapi.jsonを指定します。ファイルから読み込むツールでは、先にJSONを保存してください。

curl --fail 'https://api.genko.me/openapi.json' -o genko-openapi.json

定義内のサーバーURLはhttps://api.genko.me/v1です。リクエストするときは、workspaceにワークスペースID（スラッグ）、endpointにAPIのエンドポイントを指定します。認証設定はApiKeyHeaderで、送信するヘッダー名はX-API-KEYです。

定義の取得に認証は不要ですが、コンテンツやスキーマの取得にはAPIキーが必要です。 キーの有効期間と対象APIはAPIキーの管理で確認してください。

ワークスペースのスキーマとの違い

公開OpenAPIは、すべてのワークスペースに共通するHTTP仕様です。各利用者が作成したAPI名やフィールド定義、記事本文、APIキーは含みません。

コンテンツのユーザー定義フィールドは任意のキーとして扱い、一覧とオブジェクト形式の応答は同じパスに記述されています。OpenAPIから生成した型だけでは、自分のblogにtitleやbodyがあることまでは表せません。

ワークスペース固有の定義は認証付きの/v1/{workspace}/_schemaで取得します。TypeScriptの型付きクライアントを使う場合はCLIのinit・pullで生成してください。キーの対象が限定されている場合、スキーマにもその対象APIだけが含まれます。

APIカタログを読む

curl --fail 'https://genko.me/.well-known/api-catalog'

レスポンスはapplication/linkset+json形式で、配信APIを指すanchorと参照先を返します。

これは製品が公開する配信APIの案内です。ワークスペース内に作成したAPIの一覧は_schemaを使います。APIカタログへのHEADでもLinkヘッダーにカタログの場所を返します。

実際の取得例は配信API、AIへ渡す製品資料はMarkdownで読むを参照してください。