GraphQLとは？
GraphQLは、複雑なデータ構造やそれらの上に構築されたインターフェースに非常に適したAPIとのやり取りの代替手段です。データを別々の独立した部分として扱うのではなく、GraphQLはデータのつながりや関連性を示し、情報を要求して受け取ることを容易にします。
GraphQLは、データベースに直接話しているかのようにAPIとやり取りできるクエリ言語と考えてください。GraphQLを使用すると、できるだけデータベースに近づくことができ、欲しいデータと取得方法を選択できるため、大幅なパフォーマンスの利点が得られます。
GraphQLはFacebookによって作成されました。複雑なデータ構造のスケーリングの問題を解決するために作成され、その成功した採用により、より多くの企業が自社のAPIにGraphQLを使用する利点を認識し始めています。
RESTとの主な違い
GraphQL APIは思っているよりも簡単に扱えます。REST APIを使用している場合、以下の基本的な違いに注意してください：
| 特徴 | REST | GraphQL |
|---|---|---|
| エンドポイント | 異なるアクションのために複数のエンドポイントにリクエストを送信 | すべてのリクエストは単一のエンドポイント（例：/graphql）に送信されます |
| データの取得 | 特定のエンドポイントでGETメソッドを使用してデータを取得 | 必要なデータをリクエストするためにクエリを使用し、過剰なデータの取得や不足を減らします |
| データの変更/アクション | データの変更や処理にPOST、PUT、PATCH、またはDELETEなどのHTTPメソッドを使用 | 操作を実行するためにmutationsを使用します（例：パーティの作成、着陸コストの計算） |
| レスポンスの形式 | 固定されたレスポンス形式は、事前に定義されたすべてのフィールドを返しますが、それが必要かどうかに関係なく | 柔軟なレスポンスにより、含めるべきフィールドを正確に指定でき、不要なデータ転送を減らします |
| データの接続 | 関連データを取得するために複数のリクエストが必要な場合があります | ネストされたクエリを使用して、関連データを1つのリクエストで取得できます（例：パーティの詳細と出荷アイテムを一緒に）。ユーザーはまた、1つのGraphQLリクエスト内で複数のmutationsを管理するワークフローを構築でき、複雑さを減らし、効率を向上させることができます |
GraphQLの利点
より迅速なレスポンス
GraphQLは、正確なデータの取得、単一のエンドポイントの使用、およびバッチ処理やキャッシュ機能の向上により、より迅速なレスポンスを提供します。
正確なデータの取得
RESTの一般的な課題は、データの過剰取得または不足です。GraphQLは、必要なデータだけをリクエストできるため、不要な情報を取得することなく必要な情報を取得できます。この具体性はパフォーマンスを向上させるだけでなく、APIとやり取りする人々にとってプロセスを簡素化し、システムをより効率的かつユーザーフレンドリーにします。
これが役立つ例：
- フロントエンド開発者は、UIコンポーネントに必要なデータのみを取得できるため、サーバーへのラウンドトリップ数が減少し、パフォーマンスが向上します。
- HSコード分類カートナイゼーション、出荷評価、およびlanded costの見積もりを、checkout内のアイテムに対して取得したいとします。GraphQL APIを介して統合している場合、必要ワークフローを含めて、1回の呼び出しで必要なすべての情報を取得できます。一方、REST APIを使用している場合、まClassify REST APIを呼び出し、その後別々Rating REST APIを呼び出し、最後Landed Cost REST APIにその分類と出荷評価を差し込む必要があります。これらのREST APIはすべて可能な限りすべての情報を返し、必要なデータを見つけるためにレスポンスを解析する必要があります。この速度の向上は、ショッパーが去る前に迅速に完全なlanded costを返すことに影響を与えます。
単一のエンドポイント
GraphQL APIには通常、複数のエンドポイントがありません。これは、REST APIが異なるリソースやアクションのために複数のエンドポイントを持つのとは対照的です。これにより、APIの管理と理解が簡素化されます。
バッチ処理とキャッシュ
GraphQLのクエリをバッチ処理する能力とキャッシュ戦略のサポートにより、大幅なパフォーマンスの向上が実現されます。これらの機能により、ネットワークとサーバーへの負荷が軽減され、ユーザーにとってより迅速で信頼性の高いやり取りが可能となります。
よく定義されたスキーマ
GraphQL APIは、強く型付けされたスキーマに基づいています。このスキーマは利用可能なデータの構造と実行可能な操作を定義します。これにより、利用可能なデータとそのアクセス方法が明確になり、開発者の生産性が向上し、エラーが減少します。たとえば、フロントエンドチームは、新しいRESTエンドポイントを待つ代わりに、グラフを探索して必要なデータを取得できます。
既存のクライアントを壊さずに改善できる能力
GraphQLで新機能を追加したり既存の機能を変更したりしても、柔軟なクエリ構造のおかげで現在の統合に影響を与えることはありません。この機能により、既存のクライアントとの互換性を壊さずに改善を行うことができます。
最新のドキュメント
GraphQLの内省機能により、ドキュメントは自動的に生成され、変更ごとに更新されます。これにより、開発者に提供されるすべての情報が最新であることが保証され、古いドキュメントに関連する統合の問題やサポートチケットが減少します。これは、REST APIのドキュメントでよくある問題に対処します。
GraphQLのドキュメントRESTのドキュメントをご覧ください。
アナロジー
レストランにいて、好きなように料理を注文できるメニューがあると想像してください。別のレストランでは、セットメニューからしか選べません。GraphQLは最初のレストランのようなものです：
- 正確に欲しいものを手に入れる: GraphQLを使えば、必要なデータを正確に要求できます。多すぎず、少なすぎず。たとえば、料理の名前と価格だけが欲しい場合、全ての材料リストを取得する必要はありません。REST APIでは、料理の詳細全体を取得し、必要ない部分を無視しなければなりません。
- カスタム料理を作成する: 私たちのGraphQL APIは、バイキングスタイルのレストランのように、既存の材料を使って必要なものを正確に作成できるように、簡単に組み合わせることができます。それに対して、REST APIは、バスケットにパッケージされた既製品を持つベーカリーのようなもので、すでに作成されたものしか注文できず、欲しい部分だけを持ち帰ることはできません。
- 待ち時間が少ない: 必要な情報を1回のリクエストで取得できるため、サーバーに前菜、メインコース、デザートを一度に持ってきてもらうようなものです。コースの間に待つ必要はありません。ほとんどのREST APIでは、異なる情報を取得するために複数のリクエストを送信する必要があります。
- 注文の変更が簡単: アプリのデータニーズが変わった場合、GraphQLでは調整が簡単です。必要なものに対してクエリを変更するだけです。RESTでは、キッチン（バックエンド）がメニューのために新しい料理（エンドポイント）を作成するのを待たなければならず、時間がかかります。
GraphQLは、特にニーズが変化したり成長したりする際に、データを取得するための柔軟性、効率性、シンプルさを提供します。
ZonosがGraphQLを使用する理由
過去数年間にわたり、プラットフォームを近代化する中で、ZonosはAPIの新機能をRESTではなくGraphQLを使用して構築することを選択しました。この決定は、私たちのデータが複雑で相互に関連しているためであり、これはFacebookがGraphQLを作成するに至ったデータと似ています。この複雑さは、開発者がデータを取得し使用する方法が実装によって大きく異なるため、スケーラブルなREST APIを構築するのが難しくなります。
GraphQLは、私たちのAPIを実装する開発者が正確に欲しいデータを選択し、どのように取得するかを決定できるようにすることで、この問題をうまく解決します。これにより、Zonosがすべての状況に対してカスタム作業を行う必要がなく、彼らのワークフローにフィットさせることができます。
GraphQLを使用し、プラットフォームの近代化を行った結果、私たちのAPIはよりパフォーマンスが向上し、Zonosをシステムに統合するのが速くなり、Zonosが新機能をより迅速に提供できるようになりました。
より良い機能
Zonosは新機能を継続的に開発しており、GraphQLが最初（通常は唯一）の更新を受けるものです。それに対して、私たちのREST APIはエンドオブライフと見なされており、多くの新機能に直接アクセスすることはできません。
GraphQLに限定された機能の例：
- Inclusive pricing
- ラベルAPI
- 新しいCheckoutおよびHello
- APIレスポンスのボックスサイズ
- ダッシュボードレポート
- 可能であればDDP見積もりをリクエストする機能。ただし、そのサービスレベルでDDPがその国で利用できない場合はDDU見積もりを返す
- 税金、手数料の詳細な内訳（アイテムレベルの情報、特定の手数料）—ダッシュボードはGraphQLによって駆動され、すべてのストアに対してこのデータを表示しますが、REST APIレスポンスにはこのレベルの詳細が含まれていません
- テストモード（近日公開予定）
GraphQLの利点
RESTよりもGraphQLを介して統合することをお勧めする理由をご紹介します。
Zonosでは、統合のためにGraphQLとRESTの2つの主要なAPIタイプを提供しています。REST APIは長い間存在しており、多くの人にとって馴染み深いかもしれませんが、私たちはより柔軟性と迅速なイノベーションを可能にするためにGraphQLに移行しました。両方のサポートは続けられていますが、このガイドでは、GraphQLが当社の統合の未来だけでなく、一般的な統合の未来であり、今日のニーズに対応するためのより強力なツールである理由を説明します。