REST APIとGraphQLは、どちらもクライアントとサーバー間の通信を実現する技術ですが、データ取得の仕組みに違いがあります。本ブログでは、それぞれの特徴や構造を比較し、適切な選択をするためのポイントを詳しく解説します。
REST API と GraphQL は、どちらも広く使われている API の構築・利用方法です。
REST API と GraphQL の概要
REST API と GraphQL は、どちらもクライアントとサーバー間の通信を可能にする技術です。 APIの設計やデータの取得方法に違いがあり、それぞれの特性に応じた使い分けが求められます。
REST API のイメージ
レストランを想像してください。メニューにある料理のみ注文でき、カスタマイズはできません。 ウェイターに注文すると、キッチンはその料理を提供します。REST API もこれと同じ仕組みで、事前に定義されたエンドポイントからデータを取得します。
GraphQL のイメージ
次に、ビュッフェ形式を想像してください。好きな料理だけを選び、不要なものは除外できます。 「もやしとネギ抜きのラーメンがほしい」と指定すると、その通りの内容で提供されます。GraphQL API は、クライアントのリクエストに応じて、必要なデータのみを返す仕組みです。
REST APIの構造
RESTful API は通常、リソースベースの設計で構成され、HTTPメソッドを使用します。
1. HTTPメソッド
REST APIでは、標準的なHTTPメソッドを使ってリソースとやり取りします。
GET:データを取得(例:GET /applicants)
POST:新しいデータを作成(例:POST /applicant/123)
PUT:既存のデータを更新(例:PUT /applicant/123)
DELETE:データを削除(例:DELETE /applicant/123)
2. エンドポイントの構造
REST APIでは、各リソースごとに固有のURL(エンドポイント)があります。
クライアントはこれらのエンドポイントにリクエストを送り、サーバーは構造化されたデータ(多くの場合JSON形式)で応答します。
例1 — サービスのリクエスト:
リクエスト:
GET https://api.example/services/
レスポンス:
[ { "id": 123, "type": "HR_management_system" }, { "id": 456, "type": "logistic_system" } ]
例2 — 商品のリクエスト:
リクエスト:
GET https://api.example/product/456
レスポンス:
{ "id": 456, "name": "Wireless Keyboard", "price": 49.99, "availability": "in_stock" }
このように、特定のエンドポイントにアクセスすることで、指定した商品情報がJSON形式で返されます。
3. RESTの基本原則
RESTは以下の原則に従って設計されます。
- ステートレス:各リクエストは独立しており、サーバーは過去のやり取りを記憶しません。
- 一貫したインターフェース:リソースベースの一貫性あるURL構造を使用します。
- キャッシュ可能:レスポンスをキャッシュすることでパフォーマンスを向上できます。
GraphQL APIの構造
1. HTTPメソッド と エンドポイントの構造
GraphQLも標準的なHTTPメソッドを使用しますが、GraphQLもHTTPメソッドを使いますが、基本的にはPOSTがメインです。GETが使われることもあります。RESTとは異なり、GraphQLでは通常単一のエンドポイント(例:/graphql)しか公開しません。
URLにリソース名を指定することはなく、代わりにリクエストボディ内で取得したい項目(フィールドやフィルター、ネストされたデータ)を明示的に指定します。
また、HTTPの機能(ヘッダー、ステータスコード、一部キャッシュなど)も引き続き使用されます。
2. スキーマ定義
APIリクエストを行うには、スキーマの定義が必要です。
スキーマ(Schema)とは、送受信されるデータの構造(型)のことです。
例:
ステップ1:スキーマ定義
# ユーザーの型(サーバーから返されるデータの構造) type User { id: ID! name: String! email: String! phone: String address: String }
# ユーザー作成時にクライアントが送るデータ(入力型) input CreateUserInput { name: String! email: String! }
# ユーザーを作成するミューテーション(データ変更) type Mutation { createUser(input: CreateUserInput!): User }
# IDでユーザー情報を取得するクエリ(データ取得) type Query { user(id: ID!): User }
ステップ2:クライアントが送信する内容
{ "query": "mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id name email } }", "variables": { "input": { "name": "Alice", "email": "alice@example.com" } } }
ステップ3:サーバーからのレスポンス
サーバーは、スキーマに従ってUserオブジェクトを返します
{ "data": { "createUser": { "id": "1", "name": "Alice", "email": "alice@example.com" } } }
Note:
スキーマにこう書かれているとき:
type Query { user(id: ID!): User }
これは以下のことを意味します:
IDでユーザー情報をリクエストする
サーバーは User タイプで定義されているすべてのフィールドを返すことができる
しかし、サーバーはクエリで明示的に指定したフィールドだけを返す
例:もしこうクエリしたら
{ "query": "query GetUser($id: ID!) { user(id: $id) { id email } }", "variables": { "id": "1" } }
返ってくるのは id と email のみです。
User に name や phone、address といった他のフィールドがあっても返りません。
Great! これがGraphQLの強み:
クライアントが欲しいデータを正確に指定できる
3. Apolloとは
Apolloは、GraphQLを実装するためのツールやライブラリを開発している会社およびエコシステムです。Apolloのツールを使うことで、バックエンドとフロントエンドの開発者が、GraphQL APIをより簡単に構築・運用・利用できるようになります。
Apollo Server
GraphQLのバックエンドサーバーを簡単に構築できるようにするツールです。
例:スキーマを定義する
type Query { user(id: ID!): User } type User { id: ID! name: String! email: String! }
Apollo Client
const GET_USER = gql` query GetUser($id: ID!) { user(id: $id) { id name email } }`; const { data, loading, error } = useQuery(GET_USER, { variables: { id: "1" }, });
RESTとGraphQLのスキーマ定義
GraphQLではスキーマの定義が必須ですが、REST APIでは技術的には必須ではありません。 しかし、最近のREST APIプロジェクトではOpenAPIを利用し、スキーマを定義するケースが増えています。
OpenAPIの主なメリット
- ドキュメント生成:人間にも機械にも読みやすいAPI仕様書を生成
- 一貫性のあるAPI設計:リクエスト・レスポンスのフォーマットを統一
- ツール連携:APIクライアント(例:TypeScriptのAPIファイル)を自動生成
- 型安全性の向上:フロントエンド開発者がTypeScriptの型補完機能を利用可能
- バリデーション機能:バックエンドでリクエストの検証が可能
結局のところ、RESTかGraphQLかを選択する際は、チームがAPIをどのように設計・運用・スケールさせるかが鍵となります。
まとめ
REST API と GraphQL は、それぞれ異なる特性を持ちます。 RESTはシンプルで分かりやすい設計、GraphQLは柔軟なデータ取得が可能です。 プロジェクトの要件や開発環境に応じて、適切な技術を選択することが重要です。
この情報は役に立ちましたか?
カテゴリー: