• ビジョン
• GraphQLとの連携
  • GraphiQL
  • GraphQLの例を見る
• 破壊的な変更
  • 将来の変更スキーマに対する検証
  • 非推奨および削除プロセス
    • 非推奨の例
  • 削除項目一覧
• 利用可能なクエリ
  • 多重クエリ
• 限界
  • クエリの最大複雑度
• スパムとして検出された変異の解決

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機能をご覧ください。

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

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 メジャーリリースで完全に削除されます。

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

• スキーマ。
• GraphQL API リファレンス。
• リリース投稿からリンクされている非推奨機能削除スケジュール。
• GraphQL APIのイントロスペクションクエリ。

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

非推奨の例

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

削除項目一覧

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

利用可能なクエリ

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

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

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

多重クエリ

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

限界

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

クエリの最大複雑度

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

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

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

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

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

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 サービスが設定されている場合、次のような応答が返されます：
  • needsCaptchaResponse をtrue に設定してください。
  • spamLogId とcaptchaSiteKey フィールドのセット。

  使用例：

   {
     "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-Response とX-GitLab-Spam-Log-Id ヘッダを設定してリクエストを再送信してください。

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"