例えば REST API の場合は、API の使用方法(仕様書、エンドポイントなど)を Swagger などでまとめる必要があるが、GraphQL の場合は GraphiQL を使えばAPI仕様書としての役割を果たしたり、自分が欲しいデータだけを調べて取得することができるので、REST API と違い無駄なペイロード(送信データ)が発生したり、遅延や負荷がかかりにくくなる。
また Codegen を使って型を生成できるのも魅力。
RESTしか知らない人が押さえておくポイントとしては、上記にも書いたが、エンドポイントがひとつになること。どんなリクエストも /graphql に向けられるため、発想の転換が必要になる。
またRESTによくある仕様変更にともなうバージョン指定設計(api/v1/〜、api/v2/〜 など)が必要なくなる。
これはすなわち REST API の設計で生じるバージョンによる破壊的変更がなくなることを意味する。
※ そもそもGraphQLはクライアントが必要な情報のみをリクエストする形式であり、API設計ではいままであったフィールドを削除することは推奨されておらず、追加していく方式「add-only-approach」を推奨している
これらを留意して設計するといい。