SPA・SSR開発を行う上で重要なWeb APIとその周辺の基礎知識
はじめに
近年、SPAやSSRといった設計構造でアプリケーション開発を行うことが一般的になりつつあります。
SPA・SSRのアプリケーション開発を行うにあたっては、Web APIの基礎を知っておく必要があります。
本記事では、SPA・SSR開発を行う上で重要な、Web APIとその周辺の基礎知識について、
- そもそもWeb APIとは何か
- RESTアーキテクチャに従ったREST API
- REST APIの問題点を解決するGraphQL
の3つにポイントを絞って、それぞれ説明してゆきます。
目次
- Web APIとは
- REST APIの概要
- REST APIでのリソース操作
- REST APIの問題点
- GraphQLとは
- GraphQLのメリット
- GraphQLのデメリット
- まとめ
Web APIとは
Web APIとは、WebサーバーまたはWebブラウザーのためのアプリケーション・プログラミング・インターフェースのことです。
サーバーサイドのWeb APIは、一般的には、HTTPベースのWebサーバーによって定義された、1つまたは複数の一般公開エンドポイントへのリクエストと、JSONまたはXMLで表現されたレスポンスメッセージから成る、プログラム上のインターフェースのことを指します。
URI設計
Web APIのエンドポイントを実装する上で、「URI設計」についての基礎知識は大切です。
URIとは「Uniform Resource Identifier（統一リソース識別子）」の略称です。
Webが普及した頃は、URIが変わりやすく、ユーザーにとっては使いにくいものでした。
クールURIとは、変わらないURIのことで、Berners-Lee氏の「URIは変わらないべきである。変わらないURIこそが最上のURIである」という言葉から来ています。
では、どうすれば変わらないURIを設計できるのか？というと、以下のポイントを抑えることが大切になってきます。
ポイント1
プログラミング言語に依存した拡張子などを含めない。
| 良い例 | 悪い例 |
|---|---|
http://example.com/login |
http://example.com/login.php |
ポイント2
メソッドやセッションIDを含めない。
| 良い例 | 悪い例 |
|---|---|
http://example.com/login |
http://example.com/login?action=showPage |
http://example.com/login?sessionid=12345 |
ポイント3
URIはリソースを表現する名詞にする。
| 良い例 | 悪い例 |
|---|---|
http://example.com/user/123 |
http://example.com/user/show/123 |
HTTPレスポンスステータスコード
Web APIのレスポンスを実装していく上で、大切になってくるのが「ステータスコード」と呼ばれるものです。
HTTPはリクエスト/レスポンス型のプロトコルです。
ステータスコードとは、レスポンスメッセージに含まれるリクエストの結果を表す3桁の数字です。
サービスやWeb APIを設計するにあたって、ステータスコードをどのように選択するかは重要です。
レスポンスに間違ったステータスコードを割り当ててしまうと、クライアントが混乱し、システムに支障をきたしてしまいます。
レスポンスメッセージの1行目にあるステータスラインは、プロトコルバージョン、ステータスコード、テキストフレーズからなりますが、この中でも最も重要なのがステータスコードです。
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
<html>...</html>
よく使われるステータスコード
| ステータスコード | 意味 |
|---|---|
| 200 OK | リクエスト成功 |
| 201 Created | リソースの作成成功 |
| 302 Found | リダイレクト |
| 301 Moved Permanently | リソースの恒久的な移動 |
| 303 See Other | 別URIの参照 |
| 400 Bad Request | リクエストの間違い |
| 401 Unauthorized | 認証失敗 |
| 403 Forbidden | 閲覧禁止 |
| 404 Not Found | リソースの不在 |
| 500 Internal Server Error | サーバ内部エラー |
401と403は似ていますが、以下のような違いがあります。
- 401 Unauthorized
- 認証されてない場合や、不正な認証の場合に返すステータスコード
- 403 Forbidden
- ユーザは認証されているが、指定したリソースに対して要求された操作を実行する権限がない場合に返すステータスコード
REST APIの概要
REST APIとは、Web APIのうち、RESTというアーキテクチャスタイルに従っているものをいいます。RESTはAPIに限ったものではなく、Web全体のベースとなっているアーキテクチャスタイルで、REST自体クライアント／サーバ、ステートレスサーバ、統一インタフェースなど、複数のアーキテクチャスタイルを組み合わせて形作られています。
残念なことに（？）、世の中のREST APIと呼ばれているものすべてが、RESTの原則に基づいているかというとそうでもないようで、「いくつかの重要な原則」をおおまかに守るだけにとどまる、いわば「RESTっぽいAPI」が散見されるようです。
「いくつかの重要な原則」のうち、RESTの一番の特徴といえるのは、統一インターフェースでしょう。リソースに対する操作を、限られたインターフェースだけで行うというもので、HTTPを用いるREST APIではGETやPOSTなどの、決まったメソッドだけを使ってURIにリクエストを送ります。好き勝手なメソッドを追加したりすることを制限することで、システムを簡潔に構築することができます。
RESTっぽいAPIが悪で、RESTの原則を完璧に守ることが正しいのかというと、必ずしもYESと言えないのが今の環境です。次のようなURIは、過去にMicrosoft社がREST APIのガイドラインとして公開した資料に記載されていたものですが、バージョン情報をパスに含めている点で、RESTの原則から外れていると言えます。しかし、異なるバージョンを並行してサポートできるなどのメリットもあり、このような形でURIにバージョン情報を含めるよう推奨している組織も多いです。
https://api.contoso.com/v1.0/people/jdoe@contoso.com/inboxREST APIでのリソース操作
RESTのすべてについては書ききれないので、リソース操作に絞って見てみましょう。
先ほどREST APIでは統一インタフェースのスタイルに則り、限られたメソッドのみを用いてリソースに対する操作の種類を指定する、という話が出ました。主なHTTPメソッドには次のようなものがあり、中でも下4つのGET、POST、PUT、DELETEがよく使われます。
| メソッド | 安全 | べき等 | 意味・主な用途 |
|---|---|---|---|
| GET | ○ | ○ | リソースの取得 |
| POST | リソースの作成 | ||
| PUT | ○ | リソースの更新 | |
| DELETE | ○ | リソースの削除 | |
| PATCH | 差分によるデータ更新（既にリソースが存在する場合のみ） | ||
| HEAD | ○ | ○ | リソースのヘッダの取得 |
| OPTIONS | ○ | ○ | リソースがサポートしているメソッド一覧の取得 |
上の表の項目の一つ、「安全」とは、実行してもサーバ上のリソースを変化させないものを言います。
べき等は、サーバのリソースに変化を与えますが、何度実行しても結果が変わらないものです。
べき等性の例として、「0の乗算」がわかりやすいです。
例えば、「2」というリソースに対して、「×0」という操作を行うと、結果は0となります。
この「×0」という操作はべき等であるため、今後さらに「×0」、「×0」、「×0」・・・と何度操作が繰り返されても、当初の結果である0から変わることはありません。
こうしたメソッドの特性をよく理解しておくことが、REST APIの設計においては重要です。
べき等なPUTメソッドでは、同じ内容で何度呼び出しをしても更新結果は変わらず、べき等でないPOSTで呼び出しを繰り返すと、同じリソースがいくつも作成されることになります。もし、PUTで受け付ける処理で差分の更新はなく、リソースを新しく作るような設計をしてしまうと、利用者の意図しない結果を招くことになってしまいます。
そのため、APIを開発する側と利用する側の双方がメソッドの用途と特徴をよく知って使い分けることが大切です。
REST APIの問題点
ここまでREST APIについて触れてきましたが、REST APIにも以下のような問題点が存在します。
オーバーフェッチング問題
REST APIだと1つのリクエストで数多くの情報を返すため、名前のみの情報しか必要ない場合でもメールアドレス、住所、電話番号などの情報も取得してしまいます。
データはメモリに蓄積されるので、不要なデータもメモリ上に蓄積されメモリリークを引き起こす原因になる可能性があります。
リクエスト数の増加
REST APIの場合、1回のリクエストでは欲しいデータを取得できない場合があります。
例えば、ログインしているユーザとそのユーザに紐づくフォロワーのデータが欲しい場合があるとします。
エンドポイントは以下の場合とします。
- /users/{user_id}（ユーザ情報取得）
- /users/{user_id}/followers（フォロワー情報取得）
ユーザ情報を取得するエンドポイントを叩いた後にフォロワーを取得するエンドポイントを叩く必要があり、2回リクエストが必要になります。
リクエストが多くなればなるほど、通信コストが大きくなってしまいます。
これらのREST APIの問題点を解決するために、新たにGraphQLが開発されました。
GraphQLとは？
GraphQLはAPIのクエリ（問い合わせ）言語であり、既存のデータに対してクエリを実行するためのランタイム（プログラムの実行時に必要なもの）です。
2012年ごろにFacebook社が開発をスタートし、2015年にオープンソース化されました。
オープンソース化後、JavaScript、PHP、Scala、Python、Rubyなどの様々なプログラミング言語でGraphQLを使用することが出来るようになり、FacebookはもちろんのことGitHubやTwitterなどに導入されている実績があります。
GraphQLは「クエリ言語（フロント側、リクエスト）」と「スキーマ言語（サーバ側、レスポンス）」の2つによって構成されています。
クエリ言語
GraphQLサーバーに対して、リクエストするための言語でデータ取得系の「query」、データ更新系の「mutation」、サーバーサイドからのイベント通知である「subscription」の3種類が存在します。
| クエリの種類 | 意味 | 効果 |
|---|---|---|
| query | データ取得系 | GET |
| mutation | データ更新系 | POST/PUT/DELETEなど |
| subscription | イベント通知 | Websocket |
スキーマ言語
GraphQL APIの仕様を記述するための言語です。
クエリ言語からのリクエストはスキーマ言語で記述されたスキーマに従って、GraphQL処理系により実行され、レスポンスを生成します。
スキーマ言語でGraphQL APIの仕様の定義のみを行うので、実際のデータ操作はリゾルバという、特定のフィールドのデータを返す関数（メソッド）で行われます。
GraphQLのメリット
必要なデータを最小限のリクエストで取得可能
取得したいデータを指定して、リクエストをすることができます。
ログインしているユーザの名前のみを取得したい場合は名前のみを指定すれば、良くなります。
また、ログインしているユーザとそのユーザに紐づくフォロワーを取得したい場合において1回のリクエストで取得することが可能です。
これにより、必要なデータのみを最小限のリクエストで取得することができるため、通信の無駄を防ぐことができ、パフォーマンスの向上につながります。
エンドポイントの管理に苦しまない
REST APIの場合、エンドポイントを各処理ごとに増やす必要があります。
GraphQLの場合、エンドポイントが1つのためエンドポイントの管理に苦しむことがありません。
GraphQLのデメリット
GraphQLにはデメリットもあります。
オープンソース後からまだ7年と比較的新しいので、RESTに比べるとノウハウが蓄積されていません。
また、キャッシュやパフォーマンス分析はREST APIではエンドポイントごとに対応可能ですが、GraphQLではエンドポイントが1つしか存在しないため、REST APIに比べると難しいというデメリットがあります。
まとめ
いかがでしたでしょうか？REST APIとGraphQL、どちらも一長一短ですが、メリット・デメリットを理解した上で、選択・検討することが重要です。
Webサイト・システムの
お悩みがある方は
お気軽にご相談ください
出張またはWeb会議にて、貴社Webサイトの改善すべき点や
ご相談事項に無料で回答いたします。
