HTTP を介した提供

HTTP は、その遍在性から、GraphQL を使用する場合のクライアントサーバープロトコルとして最も一般的な選択肢です。HTTP 上で動作するように GraphQL サーバーを設定するためのガイドラインを以下に示します。

Web リクエストパイプライン#

最新の Web フレームワークのほとんどは、リクエストがミドルウェア（別名フィルター/プラグイン）のスタックを通過するパイプラインモデルを使用しています。リクエストがパイプラインを流れると、検査、変換、変更、またはレスポンスによる終了を行うことができます。GraphQL はすべての認証ミドルウェアの後に配置する必要があります。これにより、HTTP エンドポイントハンドラーと同じセッションおよびユーザー情報にアクセスできます。

URI、ルート#

HTTP は一般的に REST と関連付けられており、REST はコアコンセプトとして「リソース」を使用します。対照的に、GraphQL の概念モデルはエンティティグラフです。そのため、GraphQL のエンティティは URL では識別されません。代わりに、GraphQL サーバーは通常 /graphql の単一の URL/エンドポイントで動作し、特定のサービスに対するすべての GraphQL リクエストはこのエンドポイントに向けられる必要があります。

HTTP メソッド、ヘッダー、およびボディ#

GraphQL HTTP サーバーは、HTTP GET および POST メソッドを処理する必要があります。

GET リクエスト#

HTTP GET リクエストを受信する場合、GraphQL クエリは "query" クエリ文字列で指定する必要があります。たとえば、次の GraphQL クエリを実行する場合

{
  me {
    name
  }
}

このリクエストは、次のように HTTP GET 経由で送信できます

http://myapi/graphql?query={me{name}}

クエリ変数は、variables と呼ばれる追加のクエリパラメーターで JSON エンコードされた文字列として送信できます。クエリに複数の名前付き操作が含まれている場合、operationName クエリパラメーターを使用して、実行する操作を制御できます。

POST リクエスト#

標準の GraphQL POST リクエストでは、application/json コンテンツタイプを使用し、次の形式の JSON エンコードされたボディを含める必要があります

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

operationName と variables はオプションのフィールドです。operationName は、クエリに複数の操作が存在する場合にのみ必要です。

レスポンス#

クエリと変数が送信された方法に関係なく、レスポンスはリクエストのボディで JSON 形式で返される必要があります。仕様で述べたように、クエリはいくつかのデータといくつかのエラーを引き起こす可能性があり、それらは次の形式の JSON オブジェクトで返される必要があります

{
  "data": { ... },
  "errors": [ ... ]
}

エラーが返されなかった場合、レスポンスに "errors" フィールドが存在してはなりません。データが返されない場合、GraphQL 仕様によると、"data" フィールドは、実行中にエラーが発生しなかった場合にのみ含まれる必要があります。

Node#

NodeJS を使用している場合は、サーバー実装のリストを参照することをお勧めします。

ドラフトトランスポート仕様#

詳細な HTTP トランスポート仕様が開発中です。まだ最終決定されていませんが、これらのドラフト仕様は、GraphQL クライアントとライブラリのメンテナーにとって唯一の真実の情報源として機能し、HTTP トランスポートを使用して GraphQL API を公開および使用する方法を詳細に説明しています。言語仕様とは異なり、遵守は必須ではありませんが、ほとんどの実装は相互運用性を最大化するためにこれらの標準に移行しています。