HTTP上でのGraphQL：新たなレスポンスフォーマットとリクエストハンドリングの改善

Shopify APIのバージョン2025-01から、HTTPを通じたGraphQLリクエストの取り扱いが微調整されます。これは、GraphQL over HTTP specに準拠して行われる変更で、Content-TypeとAcceptヘッダーの扱いやレスポンスステータスコードの精度向上を目指しています。

新たなレスポンスフォーマット

新たなapplication/graphql-response+jsonのレスポンスフォーマットが利用可能になります。リクエストはAcceptヘッダーを使用してこのフォーマットを選択することができます。例えば、以下のように指定します。

Accept: application/graphql-response+json, application/json

上記のように指定することで、application/graphql-response+jsonのレスポンスを優先的に受け取ることができます。この新フォーマットは、ステータスコードを除いてJSONと同一です。

200 OK

• application/graphql-response+jsonの場合、このステータスはJSONペイロードが有効であり、提出されたGraphQLドキュメントがサーバー上で実行を試みたことを示します。ただし、実行中にエラーが発生した場合や部分的なデータだけが含まれている場合でもこのステータスが返されます。
• application/jsonの場合、このステータスはJSONペイロードが有効であることのみを示します。

400 Bad Request

• application/graphql-response+jsonの場合、このステータスはJSONペイロードが無効であるか、提出されたGraphQLパラメーターが静的検証に失敗し実行されなかったことを示します。
• application/jsonの場合、このステータスはJSONペイロードが無効であることのみを示します。

利用のまとめ

2025-01バージョン以降のリクエストについては以下の通りです。

• /graphqlエンドポイントを使用します。/graphql.jsonを使用すると自動的にapplication/jsonが返されます。
• リクエストボディはspec JSON encodingを含まなければなりません。
• Content-Typeヘッダーは必ずapplication/jsonを指定しなければなりません。旧来のapplication/graphqlリクエストフォーマットはサポートされません。サポートされていないコンテンツタイプのリクエストは415 Unsupported Media Typeレスポンスが返されます。
• Acceptヘッダーはapplication/graphql-response+jsonおよび/またはapplication/jsonレスポンスフォーマットをサポートします。サポートされていないAcceptタイプのリクエストは406 Not Acceptableレスポンスが返されます。
• */*を受け入れるとapplication/graphql-response+jsonレスポンスがデフォルトとなります。

なお、この変更は現時点ではunstableバージョンやStorefront APIには影響を与えません。不安定な遷移が発生する前には、移行タイムラインとともに重大な変更の告知が行われます。

以上の内容を踏まえ、実装に際しては旧来のリクエストフォーマットから新たなレスポンスフォーマットへの移行をスムーズに行うための対策を検討する必要があります。特に、エラーハンドリングの部分については、ステータスコードの意味が変更されているため、注意が必要です。

これらの変更は、より詳細なレスポンスステータスコードとともに、APIの利用者がより正確な情報を得られるようになるため、パフォーマンスの向上につながります。

次のステップとして、現状の実装にこれらの変更を反映させ、テストを行うことが推奨されます。また、新たなレスポンスフォーマットが導入された後の開発プロセスについて、チーム内で共有と理解を深めることも重要です。

参考記事: GraphQL Over HTTP