目次 (12)
RESTful APIアーキテクチャ
REST(Representational State Transfer)は、Webを開発する際の指針を提供し、その構造を説明するために作られたソフトウェアアーキテクチャスタイルです。
1. Restアーキテクチャの特徴
Restful APIの核心は、URLをEndpointとして見るのではなく1つのリソースとして見ることであり、一貫性を持つことで予測可能になることです。以下は、Restアーキテクチャが持つ特性だそうです。
1.1 Stateless 無状態性
クライアント-サーバーのリクエストでクライアントの情報は保存されず、各リクエストは分離されていなければなりません。
1.2 Client-Server構造
クライアント、サーバー、リソースで構成されており、HTTPでリクエストが行われます。
1.3 データキャッシング
キャッシングを可能にすることで、クライアント-サーバー間のやり取りを最小限に抑えます。
1.4 一貫したインターフェース
リソースが識別可能でなければならず、クライアントに送信された表現とは区別されなければなりません。
そして、受信する表現を通じてリソースが操作されなければなりません。
自己記述的なメッセージには、クライアントが情報をどのように処理すべきかを説明する情報が十分に含まれていなければなりません。(Content-type、method、encodingなど)
1.5 レイヤードアーキテクチャのサポート
サーバーは、階層構造(セキュリティ、ロードバランシングなど)で構成された階層化システムを持つことができます。
1.6 コードオンデマンド
リクエストを受けると、サーバーからクライアントへ実行可能なコードを送信して、クライアントの機能を拡張できます。
2.メソッドとステータスのまとめ
Restful APIでは、リソースに対する行為をHTTPメソッドで表し、サーバーはこのメソッドに従って処理し、Responseでステータスコードを渡してレスポンスの状態を表現します。
2.1 メソッド
メソッド | 説明 | 主な用途 | 冪等性 (Idempotent) | 安全性 (Safe) | URIの例 |
|---|---|---|---|---|---|
GET | リソースを取得 | データの取得 | ✅ はい(同じリクエストを何度送っても結果は同じ) | ✅ はい(サーバーの状態を変更しない) | /users/1 |
POST | リソースを作成 | データの追加 | ❌ いいえ | ❌ いいえ | /users |
PUT | リソース全体を修正 | データ全体の更新 | ✅ はい | ❌ いいえ | /users/1 |
PATCH | リソースの一部を修正 | データの一部の更新 | ❌ 一般的にはいいえ(サーバーの実装によって異なる) | ❌ いいえ | /users/1 |
DELETE | リソースを削除 | データの削除 | ✅ はい(すでに削除されている場合でも同じレスポンスが可能) | ❌ いいえ | /users/1 |
OPTIONS | サポートしているメソッドの取得 | CORSのプリフライトリクエストなど | ✅ はい | ✅ はい | /users |
HEAD | リソースのヘッダーのみ取得(本文なし) | メタデータの確認 | ✅ はい | ✅ はい | /users/1 |
2.2 ステータス
ステータス | ステータスコード | 意味 | 説明 | 使用例 |
|---|---|---|---|---|
(2xx) | 200 OK | リクエスト成功 | GET、PUT、PATCH、DELETEなどで使用 | データ取得の成功 |
201 Created | 作成済み | POSTリクエストでリソースを作成するときに使用 | 会員登録、記事の作成など | |
204 No Content | コンテンツなし | 成功したが、レスポンス本文がないとき | DELETE、PUT成功後にレスポンスなし | |
(3xx) | 301 Moved Permanently | 恒久的な移動 | リソースが恒久的に移動 | URL変更の案内 |
302 Found | 一時的な移動 | リソースが一時的に別の場所にある | ログイン後のリダイレクト | |
304 Not Modified | 変更なし | キャッシュされたリソースをそのまま使用可能 | 条件付きGET(If-Modified-Sinceなど) | |
(4xx) | 400 Bad Request | 不正なリクエスト | 無効なパラメータなど | フィールドの欠落、JSONのパース失敗 |
401 Unauthorized | 認証が必要 | ログインが必要、またはトークンエラー | JWTなし/期限切れ | |
403 Forbidden | アクセス禁止 | 権限がない場合 | 管理者専用のアクセス | |
404 Not Found | リソースなし | 存在しないURIへのリクエスト | 誤ったIDで取得したとき | |
409 Conflict | 競合 | 重複したリソースを作成するときなど | 同一IDの重複作成など | |
422 Unprocessable Entity | 処理できない | 形式は正しいが意味が誤っている | フォームの検証失敗など | |
(5xx) | 500 Internal Server Error | 内部サーバーエラー | サーバー内部で例外が発生 | 予期しないエラー |
502 Bad Gateway | ゲートウェイエラー | サーバーが不正なレスポンスを受信 | プロキシ、ゲートウェイの問題 | |
503 Service Unavailable | サービス利用不可 | サーバーのメンテナンス中、または過負荷 | サーバーダウン、メンテナンス | |
504 Gateway Timeout | ゲートウェイタイムアウト | レスポンスの遅延 | バックエンドのレスポンスが遅延したとき |
3. リチャードソン成熟度モデル(Richardson Maturity Model)
リチャードソン(Richardson)は、Rest APIをうまく適用するために4段階の成熟度モデルを定義しました。

