GraphQL とは？ API のためのクエリ言語

GraphQL は、クライアントが欲しいフィールドを正確に記述し、サーバーがそのデータだけを、通常は単一のエンドポイントを通じて返す API のクエリ言語です。

多数の固定的な REST エンドポイントの代わりに、GraphQL は 1 つのエンドポイントと型付き schema を公開します。クライアントは必要な正確なフィールドを指定したクエリを送信し、サーバーは一致するデータで応答します。GitHub の API の一部を含む一部の CI 連携は GraphQL であるため、REST との違いを知っておくと役立ちます。

1 つのエンドポイント、柔軟なクエリ

GraphQL サーバーは通常、単一の URL で POST リクエストを受け付けます。body には、関連するオブジェクトにまたがってフィールドを選択するクエリが含まれ、クライアントは複数回ではなく 1 回の往復でネストされたデータを取得できます。

schema と型

GraphQL は強く型付けされています。schema はすべてのオブジェクト、フィールド、操作を宣言するため、クライアントやツールは送信前にクエリを検証でき、introspection によって API を発見できます。

query、mutation、subscription

query はデータを読み取ります。
mutation はデータを作成または変更します。
subscription は永続的な接続を通じて更新をストリーミングします。

エラー処理は異なる

GraphQL は、フィールドがエラーになった場合でもしばしば HTTP 200 を返し、問題を body 内の errors 配列に置きます。status code だけを確認するパイプラインは部分的な失敗を見逃すことがあるため、レスポンスの body も検査する必要があります。

CI/CD における GraphQL

自動化は、GraphQL API に問い合わせて、pull request のデータの取得、release の管理、deployment のステータスの読み取りを 1 回の効率的な呼び出しで行うことがあります。単一エンドポイントの設計はネットワークの往復を少なく保ち、これは遅い実行や rate limit のある実行で重要です。

一時的な障害は依然として当てはまる

GraphQL の下層のネットワークは依然として HTTP なので、timeout や reset は発生します。不具合の後に読み取り query をリトライするのは安全ですが、mutation は idempotent でない場合があります。Latchkey の runner は一時的なトランスポート障害を自動的にリトライしますが、コードは依然として idempotent でない mutation を保護すべきです。

重要なポイント

GraphQL は、1 つのエンドポイントと型付き schema を使い、要求されたフィールドを正確に返します。
エラーは 200 であってもレスポンスの body に現れることがあるため、payload を確認してください。
読み取りはリトライして安全ですが、mutation は idempotent でない場合があります。