Kibela Web API は、Kibelaのデータにアクセスするツールを開発するためのWeb APIです。他サービスからKibelaへのインポートツールなどを想定しています。
- Table of Contents
- 概要
- アクセストークン
- エンドポイント
- リクエストヘッダ
- リクエストボディ
- サンプルコード
- 利用制限
- ロギング
- リファレンスマニュアル
- フィードバックとバグレポート
- 今後の展望
Kibela Web APIはGraphQLとして提供されています。また、GraphQLの拡張仕様であるRelay GraphQL Server Specificationにも準拠しています。
「設定」→「個人用アクセストークン」からアクセストークンを生成してください。ゲスト以外のメンバーは誰でもアクセストークンを生成・使用できます。
https://my.kibe.la/settings/access_tokens
それぞれのアクセストークンには説明を書けます。関連するURL、たとえば該当アクセストークンを利用するツールのリポジトリURLなどをマークダウンで受け付けるようになっています。
アクセストークンは無期限で有効です。不要なアクセストークンは明示的に無効化 (revoke) してください。なお、ユーザーがチームから削除されたときはそのユーザーが作成したアクセストークンはすべて無効化されます。
https://${TEAM_NAME}.kibe.la/api/v1
${TEAM_NAME} はお使いのチーム名にしてください。
このエンドポイントはPOSTリクエストのみ受け付けます。
次のヘッダを指定してください。 ${ACCESS_TOKEN} はアクセストークンに置き換えてください。
Authorization: Bearer ${ACCESS_TOKEN}Content-Type: application/jsonorContent-Type: application/x-msgpackAccept: application/jsonorAccept: application/x-msgpack, application/json
また、User-Agent ヘッダは指定することを奨励します。 User-Agent はアクセストークンごとの使用履歴（ログ）にも記録されます。
リクエストやレスポンスでJSONフォーマットを利用する場合は、リクエストヘッダに Content-Type: application/json や Accept: application/json を指定してください。
Content-Type: application/jsonAccept: application/json
リクエストとレスポンスはそれぞれMessagePackフォーマットも利用できます。
リクエストをMessagePackにする場合はContent-Type: application/x-msgpackを、レスポンスをMessagePackにする場合はAccept: application/x-msgpack, application/jsonをそれぞれ指定してください。
Content-Type: application/x-msgpackAccept: application/x-msgpack, application/json
現在のところ、エラーレスポンスはJSONを返すことがあります。必ずレスポンスヘッダのContent-Typeをみてデコードしてください。
MessagePackはバイナリの転送においてオーバーヘッドがなく、また多くのMessagePack処理系においてレスポンスボディのストリーミングデコードが可能であるためJSONよりも遥かに高速にリクエスト・レスポンス処理を行えます。Kibela Web APIを利用するツールは、特に運用フェーズではなるべくMessagePackを使うことを奨励します。
なお、MessagePackを利用する場合、Kibela GraphQL schemaにおける DateTime 型はMessagePackのtimestamp typeにマップされます。timestamp typeの詳細についてはお使いのMessagePackシリアライザのドキュメントを参照ください。
リクエストボディにはqueryとvariablesを与えてください。queryパラメータはGraphQL query文字列です。 variablesはクエリに定義した変数をオブジェクトで与えてください。
これらのクエリパラメータはGraphQLの仕様に従っています。したがって、任意のGraphQL clientを利用できるはずです。
シンプルなサンプルスクリプトは次のリポジトリにあります。
またcurlを用いたシンプルな例を次に示します。 お使いのKibelaのサブドメイン名と個人用アクセストークンをセットした上で実行できます。
export SUBDOMAIN='YOUR-SUBDOMAIN'
export SECRET='secret/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
curl "https://${SUBDOMAIN}.kibe.la/api/v1" \
-H "Authorization: Bearer ${SECRET}" \
-X POST \
-d '{"query": "query { currentUser { realName } }", "variables": {}}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'User-Agent: KibelaAPITestFromCurl'Kibela Web APIは過剰な負荷を避けるためにいくつかの利用制限を掛けています。
※ 個々の具体的な制限については現在調整中です。制限は予告なく変更することがあります。
まず、1秒あたりのリクエスト数です。これは、1秒につき最大10リクエストを超えてはいけません。リクエストを連投するときは最低でも100msあけるようにしてください。この制限をこえるとHTTP status code 429 Too Many Request を返します。
1リクエストごとに最大コストが定められており、これを超えるとレスポンスボディの errors.extensions.code=REQUEST_LIMIT_EXCEEDED を返します。HTTP status codeは200です。
エラーレスポンス（抜粋）
{
"errors": [
{
"extensions": {
"code": "REQUEST_LIMIT_EXCEEDED",
}
}
]
}このエラーは再送しても必ず同じエラーを返すので、クエリを組み直してください。
現在、リクエストごとの最大コストは 10,000 です。この値は予告なく変える可能性があります。
また、1時間ごとに消費できるコストの予算 (budget) がアクセストークンとチームごとに定められており、これを超えると次のエラーになります。
- アクセストークンのバジェット超過:
TOKEN_BUDGET_EXHAUSTED - チームのバジェット超過:
TEAM_BUDGET_EXHAUSTED
エラーレスポンス（抜粋）
{
"errors": [
{
"extensions": {
"code": "TOKEN_BUDGET_EXHAUSTED",
"waitMilliseconds": 1000,
}
}
]
}このとき、同じクエリをリクエストするのであれば waitMilliseconds だけ待てば再度可能になります。
なお、予算は1msに1回復します。
現在、アクセストークンの1時間ごとの予算は 300,000 です。また、チームの1時間ごとの予算は 3,000,000 です。この値は予告なく変える可能性があります。
コストは基本的にGraphQLのフィールド1つにつき1 costです。ただし、1リクエストごとに基本コストが設定されており、かならず基本コスト分消費します。
また、connectionフィールドはかならず first または last パラメータで取得数を明示する必要があり、その「取得数 × childre node」がconnection全体のコストになります。
計算されたコストは Query.budget.cost クエリでみることができます。
なお、一部のフィールドはコストが通常よりも高いことがあります。たとえば、全文検索やmarkdownのレンダリング（ contentHtml など）はコストを高めに設定しています。
消費コストについてはバランスを調整中です。調整が終わったら詳細を公開します。
queryパラメータの値はログに保存される対象です。このログはチームの管理者にも解放される予定です。秘匿値はqueryパラメータに書かず、variablesパラメータとして与えてください。
リファレンスマニュアルは現在、「設定」→「個人用アクセストークン」→「Web API console」 (GraphiQL) の "Documentation Explorer" から利用できます。
https://my.kibe.la/api/console
このドキュメントのissuesでフィードバックとバグレポートを受け付けています。起票は日本語ないし英語でお願いいたします。
https://github.com/kibela/kibela-api-v1-document/issues
将来的に次のような拡張を予定しています。
- OAuth 2.0 への対応
- Access Token自体の情報をreadonlyでチーム全体に公開するか検討中
- Web API利用制限・予算管理の調整