コラム

2024年現在、Web開発において外部サービスのAPIを利用するのが当たり前になっています。その際、APIの仕組みとしてREST APIとGraphQLが主流となっています。

本記事では、両者の相違点を紹介し、その効率的な扱い方を解説します。

REST APIの基礎

REST APIは、HTTPメソッドとURLを使ってデータの操作を行うAPIの設計スタイルです。主要な特徴として、ステートレスであること、リソース指向であること、キャッシュ可能であることが挙げられます。

• HTTPメソッド
  データの操作（取得、作成、更新、削除）を指定
• URL
  操作対象のリソースの識別子を指定

たとえば、ユーザー（user/users）を操作する場合、以下のようにURLを指定します。

• ユーザー（複数）の取得：GET /users
• 特定のユーザーの取得：GET /users/:id
• ユーザーの作成：POST /users
• ユーザーの更新：PUT（またはPATCH） /users/:id
• ユーザーの削除：DELETE /users/:id

さらに、ユーザーが保有している情報（例：投稿。post/posts）を取得する場合、リレーションを利用して以下のように指定します。 userId はユーザーのIDで、「あるユーザー」を特定するものです。

• あるユーザーの投稿（複数）の取得：GET /users/:userId/posts
• あるユーザーの特定の投稿の取得：GET /users/:userId/posts/:id
• あるユーザーの投稿の作成：POST /users/:userId/posts
• あるユーザーの特定の投稿の更新：PUT（またはPATCH） /users/:userId/posts/:id
• あるユーザーの特定の投稿の削除：DELETE /users/:userId/posts/:id

このようにURLを見れば、何のリソースを対象としているかが分かり、HTTPメソッドを見ればどんな操作を行おうとしているかが分かるのがREST APIの特徴です。

RESTの利点

REST APIの利点は以下の通りです。

キャッシュ可能

REST APIはURLがユニークである点から、GETのキャッシュがしやすいのが利点です。同じURLに対して同じ結果が返ってくるため、最初に取得した結果をキャッシュすることでパフォーマンスを向上させることができます。

ステートレス

REST APIは個々のリクエストが独立しています。リクエスト間の異存がなければ、システムリソースの解放が容易であったり、スケーラビリティが向上するなどのメリットがあります。

リソース指向

REST APIはリソースを操作することを重視しています。そのため、リソースの識別子をURLに含めることで、リソースの操作が直感的に行えるのが利点です。

RESTの欠点

一方で、REST APIには以下のような欠点もあります。

過剰なデータ取得

一般的にREST APIでは各リソースの情報をすべて返します。ある場面ではnameだけ、別な時にはidとnameなどと使い分けることはしません。そのため、アプリケーション側にとって不要な情報を取得してしまうことがあり、パフォーマンスの低下につながる可能性があります。

ネストが深くなる

リレーションを表現するためにURLをネストすることがあります。しかし、ネストが深くなるとURLが複雑になり、リクエストの可読性が低下する可能性があります。

たとえば「あるユーザーが保有している投稿に対していいねを付けたユーザー」を取得する場合、以下のようにネストが深くなります。

GET /users/:userId/posts/:postId/likes/:likeId

バージョニング

APIの仕様が変更された場合、旧バージョンと新バージョンを同時にサポートする必要があります。これにより、APIのメンテナンスが複雑化する可能性があります。REST APIの場合、エンドポイントの最初にバージョン番号を持たせたり、クエリーストリングで指定することがあります。

GraphQLの基礎

REST APIにおける幾つかの課題が見えてきた中、登場したのがGraphQLです。GraphQLはFacebookによって開発され、2015年にオープンソース化されました。REST APIの代替として、データの取得や操作を行うための新しいクエリ言語です。

GraphQLの特徴

GraphQLの特徴は以下の通りです。

クエリ言語

GraphQLはクエリ言語であり、クライアントで欲しいデータを選んでリクエストできます。クライアントが必要なデータを指定するため、過剰なデータ取得を防げたり、関連データを一緒に取得できるのが利点です。

スキーマ

GraphQLはスキーマを持っており、データの構造や操作を定義します。スキーマを元にクエリを構築し、データの取得や操作を行います。スキーマをベースにすれば、入力補完なども可能です。

リアルタイムクエリ

GraphQLはサブスクリプションという仕組みを持っており、リアルタイムなデータの取得が可能です。たとえば、チャットアプリのメッセージの受信などに活用されます。

同一エンドポイント

GraphQLはREST APIと異なり、エンドポイントが1つです。そのため、REST APIよりもエンドポイントの管理が容易です。また、複数のクエリを1つのリクエストで送信できるのも利点です。

クエリとミューテーション

GraphQLにはクエリとミューテーションという2つの操作があります。クエリはデータの取得に使われ、ミューテーションはデータの変更に使われます。REST APIのGETとPOST/PUT/DELETEに相当します。

REST API	GraphQL
GET	クエリ
POST/PUT/DELETE	ミューテーション

GraphQLの利点

GraphQLの利点は以下の通りです。

フレキシブルなデータ取得

GraphQLはリクエストを投げる際に、レスポンスで取得したいフィールドを指定します。そのため、実行する操作によって必要なフィールドのみを取得できます。これにより、過剰なデータ取得を防ぎ、パフォーマンスを向上させられます。

関連データの一括取得

GraphQLではリレーションを利用して、関連データを一括して取得できます。たとえば、ユーザーとその投稿を一度に取得できます。これにより、複数のリクエストを送信する必要がなくなり、ネットワークトラフィックを削減できます。

リアルタイムデータの取得

サブスクリプションによって、リアルタイムなデータの取得が可能です。REST APIではプル型（クライアントからのリクエストが必須）ですが、GraphQLではプッシュ型（サーバーからの通知）が行えます。

変数

GraphQLでは変数を使ってクエリを動的に構築できます。たとえば、特定のユーザーの投稿を取得する際に、ユーザーIDを変数として指定できます。これにより、汎用的なクエリを作成し、柔軟に対応できます。

GraphQLの欠点

一方で、GraphQLにも以下のような欠点があります。

学習コスト

GraphQLはREST APIとは異なるアーキテクチャを持っています。そのため、新しい技術を学ぶ必要があり、学習コストがかかる可能性があります。どちらかと言えば、REST APIよりも学習コストが高いと言えるでしょう。

キャッシュの難しさ

GraphQLはREST APIと異なり、URLが固定されていないため、キャッシュの利用が難しいとされています。クエリの結果をキャッシュするためには、クライアント側での実装が必要です。

ネストの深さ

GraphQLではリレーションを利用して関連データを取得できますが、ネストが深くなるとクエリが複雑になり、可読性が低下する可能性があります。また、ネストが深くなるとパフォーマンスの低下につながることもあります。投稿に対する返信、またその返信など無制限の再帰的な取得はできません。

バイナリファイルの扱い

GraphQLは主にJSON形式でデータを取得しますが、バイナリファイル（画像や動画など）の取得や送信には向いていません。バイナリファイルを利用する際にはBase64エンコードなどの方法を使ったり、REST APIでmultipart/form-data形式で送信するなどの工夫が必要です。

REST APIとGraphQLの比較

REST APIとGraphQLはそれぞれ特徴が異なり、利用シーンによって使い分けることが重要です。以下に、両者の比較をまとめます。

パフォーマンス

REST APIはURLが固定されているため、キャッシュがしやすいという利点があります。一方で、GraphQLはクエリによって取得するデータを指定できるため、過剰なデータ取得を防ぎ、パフォーマンスを向上させられます。

開発効率

GraphQLはクエリ言語を使ってデータの取得や操作を行うため、開発者が必要なデータを指定しやすいという利点があります。一方で、REST APIはURLとHTTPメソッドを使って操作を行うため、リソースの操作が直感的に行えるという利点があります。

なお、クライアント側で都度クエリを組み立てると、コードが煩雑になったり、可読性が落ちます。そのため、クエリを専用ファイル内で定義しておくのが一般的です。そうなるとクエリの使い回しが増えてしまい、汎用的なクエリになりやすい傾向があります。

柔軟性

GraphQLはスキーマを持っており、データの構造や操作を定義します。そのため、データの取得や操作に柔軟性があります。一方で、REST APIはリソースを操作することを重視しており、リソースの操作が直感的に行えるという利点があります。

REST APIでは取得できるリソースをサーバー側で決定するため、クライアント側での柔軟なデータ取得が難しいとされています。一方で、GraphQLではクライアント側で必要なデータを指定できるため、柔軟なデータ取得が可能です。

エラーハンドリングとセキュリティ

REST APIとGraphQLではエラーハンドリングやセキュリティの取り扱いが異なります。

エラーハンドリング

REST APIではHTTPステータスコードを使ってエラーを表現します。たとえば、404（Not Found）や500（Internal Server Error）などがあります。一方で、GraphQLではエラーをオブジェクトとして返します。エラーオブジェクトにはエラーコードやメッセージなどが含まれます。

セキュリティ

REST APIとGraphQLのセキュリティの取り扱いも異なります。REST APIでは、HTTPメソッドを使ってデータの操作を行うため、CSRF（Cross-Site Request Forgery）やXSS（Cross-Site Scripting）などの脆弱性に注意する必要があります。

GraphQLではスキーマに沿って変数の型チェックが可能で、サーバー側のライブラリで対応しているケースが多いです。そのため、開発者側は変数を安全に利用できます。もちろんライブラリによっては未対応のものもあるので、その場合はクエリの検証を行い、クエリインジェクションなどの脆弱性に注意する必要があります。

認証・認可

REST APIとGraphQLの認証・認可の取り扱いも異なります。REST APIでは、HTTPヘッダーにトークンを含める方法が一般的です。一方で、GraphQLではクエリに認証情報を含める場合もあります。つまりヘッダーにトークンを含めるか、クエリの変数として渡すか選択できます。

ツールとライブラリ

フロントエンド開発においてREST APIとGraphQLを扱う際には、さまざまなツールやライブラリが利用されます。以下に、フロントエンド開発で役立つRESTとGraphQLのツールを紹介します。

Postman API Platform

PostmanはAPIのテストやデバッグを行うためのツールです。REST APIやGraphQLのエンドポイントに対してリクエストを送信し、レスポンスを確認できます。また、テストスクリプトを書いて自動化することも可能です。

Axios

AxiosはHTTPクライアントライブラリで、REST APIのリクエストを簡単に行うことができます。PromiseベースのAPIを提供しており、非同期処理を簡単に扱えます。

Apollo GraphQL

Apollo ClientはGraphQLのクライアントライブラリで、GraphQLのクエリやミューテーションを簡単に実行できます。キャッシュ機能やリアルタイムデータの取得など、さまざまな機能を提供しています。

GraphQL developer tools

GraphQL developer toolsは、GraphQLの開発をサポートするChrome拡張機能です。GraphQLのクエリやスキーマを確認したり、デバッグを行ったりすることができます。

GraphiQL

GraphiQLは、GraphQLのクエリを実行するためのWebベースのIDEです。クエリを書いて実行し、結果を確認することができます。また、スキーマの確認やドキュメントの閲覧も可能です。

WunderGraph Cosmo

WunderGraph Cosmoは、GraphQLのライフサイクルを管理するソフトウェアです。スキーマのバージョンや分析、ルーティングなどを管理します。

将来のトレンドと展望

フロントエンド開発において、現在はREST APIとGraphQLが数多く採用されていますが、将来的なトレンドや展望についても考えておく必要があります。

REST APIとGraphQLの進化の可能性

RESTという考えは2000年に登場し、四半世紀が経とうとしています。GraphQLにおいても、その前身であるFQL（Facebook Query Language）が2012年に登場しています。どちらもさまざまな課題を解決し、進化を遂げてきました。

APIを利用する機会は年々増えており、新しい技術的なアプローチや既存技術の進化が期待されます。REST APIやGraphQLについても、今後進化する可能性は十分考えられます。

新しい技術やアプローチ

新しい技術やアプローチとして、gRPCやサーバーレスなどが注目されています。gRPCはGoogleによって開発されたRPC（Remote Procedure Call）フレームワークで、高速な通信を実現します。サーバーレスは、サーバーの管理をクラウドプロバイダーに任せる技術で、プログラムは1つの関数だけを実行します。

HTTP/3では従来のTCPだけでなく、UDPを用いたQUIC（Quick UDP Internet Connections）を使って通信を行います。QUICはUDPのために信頼性は若干落ちますが、通信速度やパフォーマンスが向上します。これに合わせたAPIというのも今後出てくる可能性があります。

これらの技術やアプローチは、APIの開発や運用において新たな可能性を切り開くことが期待されます。

フロントエンドエンジニアとしての適応戦略

フロントエンドエンジニアとしては、新しい技術やアプローチに対応するために継続的な学習が重要です。APIの仕組みやデータ取扱いについての知識を深め、最新の技術やツールを取り入れることが求められます。

まとめ

フロントエンドエンジニアにとって、REST APIとGraphQLは欠かせない技術です。両者の特徴や利点、欠点を理解し、適切に使い分けましょう。また、新しい技術やアプローチにも注目し、継続的な学習を行い、最新のトレンドに対応することが求められます。

HexabaseではREST APIとGraphQLの両方をサポートしています。TypeScript SDKでは両APIを利用しており、APIを意識することなくデータ送受信が可能です。ぜひHexabaseをご利用ください。