- REST
- REST API
- RESTful API
- HTTP
- HTTP API
みなさんは上記についてそれぞれどんなものか説明できるでしょうか？
一度「webを支える技術」を読んで理解したと思っていたのですが、定着が甘かったみたいなので、アウトプットの一環として記事にまとめようと思います。
先輩のエンジニアと雑談混じりに会話したときに、これは改めて理解してやろうと思ったので。
結論：ひとことでまとめると
最初に大まかに分類すると、次のようになります。
| 用語 | 一言でいうと |
|---|---|
| API | ソフトウェア同士の「インターフェース」 |
| HTTP | 通信をするときの「プロトコル」 |
| HTTP API | HTTPを使って呼び出す「APIの呼び方」 |
| REST | APIをどう設計するかという「設計思想・制約」「設計原則」 |
| REST API | RESTの制約に従って設計されたAPI. webでは通常HTTPを扱う |
| RESTful API | RESTらしく設計されたAPI. |
下記の図は、現在よく見かけるHTTPベースのWeb APIを理解するために単純化したものです。
REST APIはHTTP APIとして実装されることが多いため、実務上は「HTTP APIという広い集まりの中にREST APIがある」と考えると整理しやすいです。
RESTそのものは特定の通信プロトコルを指しているものではありません。あくまでのAPIの「設計原則」そのものを指しています。
補足：RPC
RPC：Remote Procedure Call
ネットワーク越しに繋がった別のコンピュータ上のプログラムや、関数を呼び出して実行する技術になります。
よく見かけるのはgRPCなど。
REST設計とは異なり、手続である関数そのものを呼び出す設計になります。
参考：
そもそもAPIとは
APIはApplication Programming Interfaceの略です。
あるソフトウェアが、別のソフトウェアが持つ機能を利用するための接点や取り決めを指します。
たとえば、天気情報を提供するサービスが次のようなAPIを公開しているとします。
東京都の天気を取得する
利用する側は、決められた方法でAPIを呼び出せば、天気情報を取得できます。
内部でどのようなデータベースを使い、どのような処理で天気を取得しているかまで知る必要はありません。
APIとして公開された使い方だけ分かれば、その機能を利用できます。
APIはWeb上のものだけではありません。
- OSが提供するAPI
- ライブラリが公開する関数やクラス
- ブラウザが提供するWeb API
- ネットワーク越しに呼び出すAPI
これらもすべてAPIです。
つまり、APIという言葉だけでは、HTTPを使っているかどうかは決まりません。
今回扱うREST APIやHTTP APIは、APIの中でも、主にネットワーク越しに利用するAPIの話になります。
HTTPとは
HTTPはHypertext Transfer Protocolの略です。
RFC 9110では、HTTPはステートレスなアプリケーション層のリクエスト・レスポンス型プロトコルと説明されています。
簡単にいうと、クライアントとサーバーが通信するためのルールです。
ブラウザやアプリなどのクライアントがリクエストを送り、サーバーがレスポンスを返します。
HTTPでは、主に次のようなものが定められています。
- リクエストの目的を表すメソッド
- 対象を示すURI
- 追加情報を伝えるヘッダー
- 処理結果を表すステータスコード
- 実際に送受信する内容
GET、POST、PUT、DELETEなどはHTTPメソッドです。
また、HTTPで送れるものはJSONだけではありません。
HTML、画像、動画、テキストなど、さまざまな表現を送受信できます。
HTTP/1.1、HTTP/2、HTTP/3では、メッセージをネットワーク上で運ぶ方法に違いがあります。一方で、メソッドやステータスコードなどの中心的な意味は共有されています。
HTTP/1.1のメッセージ形式については、RFC 9112で定義されています。
HTTP APIとは
HTTP APIは、その名前のとおりHTTPを使って提供されるAPIです。
クライアントがHTTPリクエストを送り、APIを提供するサーバーがHTTPレスポンスを返します。
たとえば、次のようなAPIを考えます。
POST /getTask HTTP/1.1
Content-Type: application/json
{
"taskId": 42
}
このAPIはHTTPで呼び出しているため、HTTP APIです。
HTTP APIという言葉は、どのような設計原則を採用しているかよりも、HTTPで利用できるという点に注目した呼び方になります。
RESTとは
RESTはRepresentational State Transferの略です。
Roy Fieldingが2000年の博士論文で整理した、分散ハイパーメディアシステムのためのアーキテクチャスタイルです。
ここでいうアーキテクチャスタイルは、システムをどのように構成するかを考えるための制約や考え方の組み合わせです。
RESTは、HTTPのような通信プロトコルではありません。アーキテクチャスタイルになります。
RESTは、次の制約から構成されています。
- クライアント・サーバー
- ステートレス
- キャッシュ可能
- 統一インターフェース
- 階層化システム
- コードオンデマンド（任意）
これらは、Roy Fieldingの博士論文 Chapter 5で説明されています。
クライアント・サーバー
クライアントとサーバーの役割を分離します。
クライアントは画面表示や利用者とのやり取りを担当し、サーバーはデータの保持や処理を担当する、といった形です。
役割を分けることで、それぞれを独立して変更しやすくなります。
たとえば、サーバー側のデータベースを変更しても、APIとして公開した接点が変わらなければ、クライアントは内部実装を意識せず利用できます。
ステートレス
各リクエストは、そのリクエストを理解するために必要な情報をすべて含みます。
サーバーは「一つ前のリクエストで何をしたか」という会話の流れを保持している前提で、次のリクエストを解釈しません。
たとえば認証が必要なら、クライアントはリクエストごとに認証情報を送ります。
GET /tasks/42 HTTP/1.1
Authorization: Bearer xxxxx
ステートレスにすることで、どのサーバーでも一つのリクエストを処理しやすくなり、スケールアウトや障害からの復旧もしやすくなります。
一方で、毎回必要な情報を送るため、通信量が増える場合があります。
キャッシュ可能
レスポンスが再利用できるものか、再利用できないものかを判断できるようにします。
キャッシュを利用できれば、同じ情報を取得するたびにサーバーへ問い合わせる必要がなくなります。
HTTPでは、たとえば次のようなヘッダーがキャッシュ制御に使われます。
Cache-Control: max-age=60
ETag: "task-42-v3"
キャッシュは通信量や待ち時間を減らせます。
一方で、古くなった情報を返してしまわないよう、適切な制御が必要です。
統一インターフェース
RESTを特徴づける中心的な制約です。
サービスごとに完全に異なる操作方法を作るのではなく、共通したインターフェースを通してリソースを扱います。
RESTの統一インターフェースには、さらに次の4つの制約があります。
- リソースを識別する
- 表現を通してリソースを操作する
- メッセージを自己記述的にする
- ハイパーメディアをアプリケーション状態のエンジンにする
階層化システム
クライアントは、直接つながっている相手より先の内部構成を知る必要がありません。
クライアントとアプリケーションサーバーの間には、ロードバランサー、API Gateway、プロキシ、キャッシュなどを配置できます。
クライアント
↓
CDN・プロキシ・API Gateway等
↓
アプリケーションサーバー
↓
データベース
階層を追加することで、負荷分散やセキュリティ、キャッシュなどの役割を分離できます。
一方で、階層が増えるほど通信や処理の負荷が増える可能性があります。
コードオンデマンド
必要に応じて、サーバーからクライアントへ実行可能なコードを送り、クライアントの機能を拡張できるという制約です。
ブラウザがサーバーからJavaScriptを受け取って実行する例が分かりやすいです。
コードオンデマンドだけは、RESTにおける任意の制約です。
必ず採用しなければならないものではありません。
REST APIとRESTful APIとは
REST APIは、RESTの制約に従って設計されたAPIです。
RESTfulは「RESTの性質を持つ」「RESTに沿っている」という意味で使われます。
そのため、一般的にはREST APIとRESTful APIはほぼ同じ意味になります。
ただし、「どこまで満たせばRESTfulなのか」については、厳密な定義と実務上の呼ばれ方にズレがあります。
原典に沿ったREST API
原典に沿って考える場合、先ほど挙げたRESTの制約全体が重要です。
特に、次のような点まで考える必要があります。
- リソースが識別されている
- 表現を通してリソースを操作する
- メッセージが自己記述的である
- レスポンスに含まれるリンクなどから、次の状態遷移を判断できる
RESTの提唱者であるRoy Fieldingは、REST APIs must be hypertext-drivenの中で、HTTPを使っているだけのインターフェースをREST APIと呼ぶことや、ハイパーテキストの制約を欠くことを問題として挙げています。
実務でよく呼ばれるREST API
一方、実務では次のような特徴を持つAPIもREST APIと呼ばれることが多いです。
- URIを名詞にする
- HTTPメソッドを使い分ける
- JSONでデータを送受信する
- ステートレスにする
たとえば、次のようなAPIです。
GET /tasks/42
POST /tasks
PUT /tasks/42
DELETE /tasks/42
これは、操作名ではなくタスクというリソースをURIで識別し、HTTPメソッドによって操作を表しています。
一般的には、このようなリソース指向のHTTP APIがREST APIと呼ばれています。
実務で使われている呼び方を考慮して、次のように分けて理解することにしました。
厳密なREST API
RESTの制約全体に沿っているAPI
実務でよくいうREST API
RESTの考え方を一部取り入れた、リソース指向のHTTP API
まとめ
今回調べた言葉は、同じAPI開発の場面で出てきますが、それぞれ役割が違います。
API
ソフトウェア同士が機能を利用するための接点
HTTP
リクエストとレスポンスをやり取りする通信プロトコル
HTTP API
HTTPを使って呼び出すAPIの広い呼び方
REST
分散システムを構成するためのアーキテクチャスタイル
REST API・RESTful API
RESTの制約に沿って設計されたAPI
HTTPは通信のルールで、RESTは設計上の制約です。
そのため、HTTPを使っていてもREST APIとは限りません。ex.HTTP通信を使ったRPCなど。
REST APIはHTTPと相性がよく、現在のWeb開発における”API”と呼ぶもののその多くはREST原則を意識したHTTP API、今回の記事でいうところのRESTful APIのことを指しているかなと思います。
参考にした資料
- Roy Thomas Fielding, Architectural Styles and the Design of Network-based Software Architectures
- Roy Thomas Fielding, Chapter 5: Representational State Transfer（REST）
- Roy Thomas Fielding, REST APIs must be hypertext-driven
- RFC 9110: HTTP Semantics
- RFC 9112: HTTP/1.1
- RFC 1392: Internet Users' Glossary