GraphQL API

GitLab 12.1で有効になり、一般的に利用可能になりました。機能フラグgraphql を削除しました。

GraphQLはAPI用のクエリ言語です。必要なデータを正確にリクエストするために使うことができるので、必要なリクエストの数を制限することができます。

GraphQLデータは型に整理されているため、クライアントはクライアント側のGraphQLライブラリを使用してAPIを利用し、手動での解析を回避することができます。

固定されたエンドポイントやデータモデルがないため、変更を加えることなくAPIに追加することができます。これにより、バージョンレスのAPIを持つことができます。

ビジョン

私たちはGraphQL APIをGitLabとプログラムでやりとりする主要な手段にしたいと考えています。REST API で可能なことはすべて GraphQL API でも可能であるべきです。

このビジョンを達成するために、フロントエンドは新機能のために REST API よりも GraphQL を優先して使うべきです。

REST APIを廃止する予定はありません。2つのAPIを並行してサポートする技術的負担を軽減するために、可能な限り実装を共有する必要があります。

GraphQLとの連携

GitLab GraphQL APIを初めて使う場合は、GitLab GraphQL APIを始めようをご覧ください。

利用可能なリソースはGraphQL APIリファレンスで見ることができます。リファレンスはGitLab GraphQLスキーマから自動的に生成され、Markdownファイルに書き出されます。

GitLab GraphQL APIエンドポイントは/api/graphql にあります。

GraphiQL

インタラクティブなGraphiQLエクスプローラーを使用するか、https://<your-gitlab-site.com>/-/graphql-explorer の自己管理GitLabインスタンスでGraphQL APIを探索します。

詳細については、GraphiQLを参照してください。

GraphQLの例を見る

GitLab.comの公開プロジェクトからデータを引き出すサンプルクエリで作業することができます:

スタートページには、GraphQLクエリをカスタマイズするさまざまな方法が記載されています。

破壊的な変更

GitLab GraphQL APIはバージョンレスであり、APIへの変更は主に後方互換性があります。

しかし、GitLabは後方互換性がない方法でGraphQL APIを変更することがあります。これらの変更はブレークチェンジとみなされ、スキーマのフィールドや引数、その他の部分の削除や名前の変更が含まれます。ブレークチェンジを作成する場合、GitLabは非推奨と削除のプロセスに従います。

破たん変更がインテグレーションに影響を与えないようにするには、非推奨と削除のプロセスをよく理解し、将来の破たん変更スキーマに対して API 呼び出しを頻繁に検証する必要があります。

機能フラグの後ろにあり、デフォルトで無効になっているフィールドは、非推奨と削除のプロセスに従いません。

詳細については、非推奨のGitLab機能をご覧ください。

caution
GitLabは非推奨および削除のプロセスに従うようあらゆる努力をします。まれに、非推奨化プロセスが重大なリスクをもたらす場合、GitLabは重大なセキュリティやパフォーマンス上の懸念にパッチを当てるために、GraphQL APIに即座に破壊的な変更を加えることがあります。

将来の変更スキーマに対する検証

GitLab 15.6で導入されました

すべての非推奨アイテムがすでに削除されているかのように、GraphQL APIに対して呼び出しを行うことができます。こうすることで、アイテムがスキーマから実際に削除される前に、変更リリースに先駆けてAPIコールを検証することができます。

これらの呼び出しを行うには、GitLab GraphQL APIエンドポイントにremove_deprecated=true クエリパラメータを追加します(例えば、GitLab SaaS GraphQLの場合はhttps://gitlab.com/api/graphql?remove_deprecated=true )。

非推奨および削除プロセス

GitLab GraphQL APIの非推奨と削除のプロセスは、GitLabの非推奨プロセスに沿っています。

GitLab GraphQL APIから削除されるようマークされたスキーマの一部は、まず非推奨となりますが、少なくとも6つのリリースでは利用可能です。その後、次のXX.0 メジャーリリースで完全に削除されます。

項目は非推奨としてマークされます:

非推奨メッセージは、該当する場合、非推奨スキーマ項目の代替を提供します。

note
GraphQL API を使用する場合は、変更の破損を避けるために、できるだけ早く非推奨スキーマを GraphQL API 呼び出しから削除することをお勧めします。非推奨スキーマ項目のないスキーマに対して API 呼び出しを検証する必要があります。

非推奨の例

以下のフィールドは異なるマイナーリリースで非推奨となっていますが、GitLab 14.0では両方とも削除されています:

非推奨フィールド理由
12.7GitLabは伝統的にメジャーリリースごとに12のマイナーリリースを行っています。このフィールドがあと6つのリリースで利用できるように、14.0のメジャーリリースで削除されました(13.0では削除されませんでした)。
13.614.0での削除により、6ヶ月間利用可能になります。

削除項目一覧

過去のリリースで削除されたアイテムのリストを表示します。

利用可能なクエリ

GraphQL APIには、ルートレベルで以下のクエリが含まれています:

クエリ説明
projectプロジェクト情報と、イシューやマージリクエストなどの関連情報。
group基本的なグループ情報とエピック。
user特定のユーザーに関する情報。
namespace名前空間とその中のprojects です。
currentUser認証されたユーザーに関する情報。
usersユーザーの集合に関する情報。
metaDataGitLab と GraphQL API に関するメタデータ。
snippets認証されたユーザーに見えるスニペット。

新しいアソシエーションとルートレベルのオブジェクトは定期的に追加されます。最新情報についてはGraphQL API Referenceを参照してください。

ルートレベルのクエリはapp/graphql/types/query_type.rbで定義されています。

多重クエリ

GitLabは、@apollo/client/link/batch-httpを使ってクエリを一つのリクエストにまとめることをサポートしています。多重化クエリについての詳細は、GitLab がバックエンドで使っているライブラリであるGraphQL Rubyにもあります。

限界

GitLab GraphQL APIには以下の制限が適用されます。

リミットデフォルト
最大ページサイズページあたり100レコード(ノード)。APIのほとんどの接続に適用されます。特定の接続では、最大ページ・サイズの上限が異なる場合があります。
クエリの最大複雑度 200 は認証されていないリクエストに、250 は認証されたリクエストに適用されます。
リクエストタイムアウト30秒
最大クエリサイズクエリまたはミューテーションごとに10,000文字。この制限に達した場合は、変数や フラグメントを使用してクエリや変異のサイズを小さくしてください。最後の手段として空白を削除してください。

クエリの最大複雑度

GitLab GraphQL APIはクエリの_複雑_さをスコア化します。一般的に、大きなクエリほど複雑さのスコアが高くなります。この制限は、API全体のパフォーマンスに悪影響を及ぼす可能性のあるクエリの実行からAPIを保護するために設計されています。

クエリの複雑さのスコアとリクエストの制限を照会できます。

クエリが複雑さの制限を超えると、エラーメッセージの応答が返されます。

一般的に、クエリの各フィールドは1 、複雑さのスコアに加算されます。特定の引数を追加することで、クエリの複雑さが増すこともあります。

note
複雑さの上限は将来変更される可能性があり、さらにクエリの複雑さも変更される可能性があります。

スパムとして検出された変異の解決

GitLab 13.11 で導入されました

GraphQLの変異はスパムとして検出される可能性があります。もし変異がスパムとして検出され

  • CAPTCHAサービスが設定されていない場合、GraphQLトップレベルエラーが発生します。たとえば

     {
       "errors": [
         {
           "message": "Request denied. Spam detected",
           "locations": [ { "line": 6, "column": 7 } ],
           "path": [ "updateSnippet" ],
           "extensions": {
             "spam": true
           }
         }
       ],
       "data": {
         "updateSnippet": {
           "snippet": null
         }
       }
     }
    
  • CAPTCHA サービスが設定されている場合、次のような応答が返されます:
    • needsCaptchaResponsetrue に設定してください。
    • spamLogIdcaptchaSiteKey フィールドのセット。

    使用例:

     {
       "errors": [
         {
           "message": "Request denied. Solve CAPTCHA challenge and retry",
           "locations": [ { "line": 6, "column": 7 } ],
           "path": [ "updateSnippet" ],
           "extensions": {
             "needsCaptchaResponse": true,
             "captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
             "spamLogId": 67
           }
         }
       ],
       "data": {
         "updateSnippet": {
           "snippet": null,
         }
       }
     }
    
  • captchaSiteKey を使用して、適切な CAPTCHA API を使用して CAPTCHA レスポンス値を取得します。Google reCAPTCHA v2のみサポートしています。
  • X-GitLab-Captcha-ResponseX-GitLab-Spam-Log-Id ヘッダを設定してリクエストを再送信してください。
note
GitLab GraphiQL の実装ではヘッダを渡すことができないので、cURL クエリとして書く必要があります。--data-binary は、JSON 埋め込みクエリでエスケープされた二重引用符を適切に扱うために使います。
export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>"
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
curl --header "Authorization: Bearer $PRIVATE_TOKEN" --header "Content-Type: application/json" --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" --request POST --data-binary '{"query": "mutation {createSnippet(input: {title: \"Title\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"