「RESTはリソース志向で、GraphQLはユースケース志向である」という対比では、要求分析における厳密なユースケースではなく、クライアントがその場で達成したい用途をユースケースと呼んでいる。 ユーザーストーリーとユースケースの違いをそのままAPIの分類へ当てはめると、この言葉のずれを見落とす。
RESTとGraphQLが固定するもの
RESTは、名前を付けられる概念をリソースとして識別し、その表現を統一されたインターフェースで操作する。 サーバーが安定した対象と意味を公開し、クライアントはその対象をたどる。 ここでいうリソースはデータベースの一行に限らず、検索結果や現在の天気のような、識別できる概念も含められる。 したがって、RESTを単純なデータの作成、読み取り、更新、削除と同一視する必要はない。
GraphQLは、サーバーが型とフィールドからなるグラフを公開し、クライアントが一回の操作で必要なフィールドを選ぶ。 同じスキーマに対して、注文一覧画面は注文番号と状態を選び、注文詳細画面は商品、支払い、配送予定まで選べる。 クライアントの用途が操作と応答の形を決めるため、この性質がユースケース志向と呼ばれる。
query OrderDetails($id: ID!) {
order(id: $id) {
number
status
items {
productName
quantity
}
payment {
status
}
}
}この操作は「注文詳細を確認する」という用途に合った形をしている。 しかし、サーバー側に注文詳細ユースケースという専用の入り口があるわけではない。 クライアントが、注文、商品、支払いという再利用可能なフィールドを用途に合わせて合成している。
要求分析のユースケースとの距離
要求分析のユースケースは、一人の主要な登場人物が目的を達成するための基本シナリオと代替シナリオを束ねる。 注文詳細を取得する一回のGraphQL操作は、多くの場合、ユースケース全体よりも一つの画面やシナリオ内の一段階に近い。 利用者が注文を開き、配送状況を確認し、必要なら問い合わせを始めるシナリオでは、複数のGraphQL操作が発生し得る。
更新操作は、読み取りよりユースケースに寄せやすい。 たとえば `confirmOrder` や `cancelOrder` という変更フィールドは、利用者の目的を表すコマンドとして設計できる。 一方で `updateOrder` のような汎用的な変更フィールドも定義できるため、GraphQLの仕様がユースケース単位の設計を強制しているわけではない。
ユーザーストーリーとシナリオとの関係
ユーザーストーリーは、価値と開発順序を話し合うための作業単位であり、通信方式の単位ではない。 一つのユーザーストーリーを実現するために複数のGraphQL操作を使うことも、既存の一つの操作を複数のストーリーから再利用することもある。
シナリオもGraphQL操作とは一致しない。 シナリオは前提から結果までの具体的な振る舞いを表し、GraphQL操作はその途中で交わされる一回の要求になり得る。 受け入れテストはシナリオを実行する過程でGraphQL操作を送信できるが、通信文を一つ送っただけでは利用者にとっての結果まで確かめたことにならない場合がある。
flowchart LR
US[ユーザーストーリー<br/>価値と開発単位] --> SC[受け入れシナリオ<br/>前提から結果まで]
SC --> O1[GraphQL操作 1<br/>表示に必要な取得]
SC --> O2[GraphQL操作 2<br/>目的を表す更新]
O1 --> SG[サーバーの型とフィールド]
O2 --> SGRESTとGraphQLの対比が示すのは、要求の種類ではなくAPI境界で構成の主導権をどこへ置くかである。 RESTはサーバーが識別したリソースと統一インターフェースを中心に据え、GraphQLはサーバーが公開したグラフからクライアントが現在の用途に合う操作を組み立てる。 GraphQLはユーザーストーリー志向やシナリオ志向なのではなく、それらから生じたクライアントのデータ要求を表現しやすい通信方式である。
https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm