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設計とは異なり、手続である関数そのものを呼び出す設計になります。

参考：

https://zenn.dev/mabo23/articles/361f7080acd467

そもそも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のことを指しているかなと思います。

参考にした資料