📚

【Web API 設計 〜 理論編 〜】RESTの核心に迫る!REST ful APIは4原則ではなかった!? RESTとROAについて

2024/03/12に公開

こんにちは、AIQ株式会社のフロントエンドエンジニアのまさぴょんです!
Web APIを実装しようとすると、必ず目にするRESTというキーワードがあります。
今回は、何となくわかった気になっていた、RESTについてあらためて学んだ結果に関して、まとめた記事になります。

実践編は、こちらです👀✨
https://zenn.dev/aiq_dev/articles/46850363412d95

今さらRESTについて書く理由と、対象読者

すでにRESTに関する記事は、日本語でもたくさんあります。
ただ「Webを支える技術 -HTTP、URI、HTML、そしてREST」を読んだり、ROAについて知った上で、いろいろな記事を見てみると、説明しきれていない記事も多々あるように見えたので、自分なりにまとめてみました。

対象読者は、次のような方々です👀🌟

RESTとは、何か?を「Webを支える技術」から読み解く

RESTに関して「Webを支える技術 -HTTP、URI、HTML、そしてREST」から引用します。

Webは、世界規模のハイパーメディアであり、分散システムです。
この巨大なシステムがなぜ動作しているのでしょうか。
それを知るために、本章ではWebの設計思想であるRESTについて解説します。
RESTはWebのアーキテクチャスタイルです。
アーキテクチャスタイルは別名「(マクロ)アーキテクチャパターン」とも言い、複数のアーキテクチャに共通する性質、様式、作法あるいは流儀を指す言葉です。
実際のシステムは、アーキテクチャを持っています。
そのアーキテクチャを設計するときに、ただ闇雲に作っていくのではなく、アーキテクチャ設計の指針、作法、流儀、つまりアーキテクチャスタイルを適用します。
システムのアーキテクチャを決定する際の羅針盤となるのがアーキテクチャスタイルです。
引用元: 「Webを支える技術 -HTTP、URI、HTML、そしてREST」

上記の引用から、RESTとは、Webのアーキテクチャスタイルであり、システムのアーキテクチャを決定する際の設計指針(羅針盤)であることがわかりました。

ちなみに、RESTは Web システムを構築するための設計思想として、Roy Fielding 氏が 2000 年に発表した論文で提唱されました。
当時は、Web の成長によってシステムを統合する必要性が高まり、分散システムに適した可用性や拡張性の高い設計が必要になっていたという時代背景があったりします。

さらに「Webを支える技術 -HTTP、URI、HTML、そしてREST」から引用を続けます。

RESTは、数あるアーキテクチャスタイルの中でも、特にネットワークシステムのアーキテクチャスタイルです。
ネットワークアーキテクチャスタイルとして最も有名なのは、クライアント/サーバー(Client/Server)です。
そしてWebは、クライアント/サーバーでもあります。
Webのアーキテクチャスタイルは、RESTでもあり、クライアント/サーバーでもあります。
これは、どういうことなのでしょうか?
実はRESTは、クライアント/サーバーから派生したアーキテクチャスタイルなのです。
素のクライアント/サーバー・アーキテクチャスタイルにいくつかの制約を加えていくと、RESTというアーキテクチャスタイルになります。
引用元: 「Webを支える技術 -HTTP、URI、HTML、そしてREST」

RESTは、ネットワークシステムのアーキテクチャスタイル(設計モデル・設計思想)であり、クライアント/サーバー(Client/Server)のベースにさらに制約条件を加えたものであることが、上記の内容からわかりました。
また、ネットワークシステムの場合は、HTTP/HTTPS通信でのやり取りがメインであることから、RESTful な Web APIは、HTTP/HTTPS通信がメインになるとわかります。


引用元: HTTPとは?HTTPSとの違いをサイト移行で実施するリダイレクト設定などをもとに解説

クライアント/サーバー(Client/Server)や、HTTP/通信に関しては、以前に記事にしていますので、わからない人は、こちらをご確認ください。
https://masanyon.com/web-http-status-code/

また、次の説明も好きなので引用します。

アーキテクチャスタイルは、特定の実装やアーキテクチャではないことに注意してください。
Webのアーキテクチャや実装は、RESTアーキテクチャスタイルに従っていますが、Web以外のアーキテクチャや実装も考えられます。
実装から抽象度を1つ上げたのが、アーキテクチャで、アーキテクチャから抽象度を1つ上げたのがアーキテクチャスタイルです。
ただし、現実には、RESTと言えば、Webのアーキテクチャスタイルを指す場合が多いので、以降ではRESTの実装例として、Webを用います。
引用元: 「Webを支える技術 -HTTP、URI、HTML、そしてREST」

つまり、RESTアーキテクチャスタイルは、Web以外でも適用できる設計原則(設計思想)であると明言されています。
また 「実装 -> アーキテクチャ(設計) -> アーキテクチャスタイル(設計思想)」 の順で、抽象度が上がるという具体から抽象のフローについての指摘もわかりやすいです。

RESTにおける重要概念: 「リソース」(Resource)と「URI」

RESTにおける重要概念の1つに「リソース」(Resource)があります。
RESTを理解するためには、リソースについての理解が不可欠です。
Web上には、多様なリソースが存在します。
リソースを一言で説明すると「Web上に存在する、名前を持ったありとあらゆる情報」となります。
リソースの名前は、あるリソースを他のリソースと区別して、指し示すためのものです。
リソースの名前とは、URIのことです。
Web上のリソースは、URIで識別します。
今でこそ、当たり前となったWebのURIですが、これは画期的な発明だったと言われています。
URIがある現在では、特定のファイルの取得方法を詳しく自然言語で説明する必要はありません。
URIを1行書いて、アクセスしてもらうだけで十分です。
URIが備える、リソースを簡単に差し示せる性質のことを 「アドレス可能性」(Addressability) と呼びます。
リソースをアドレス可能な状態、すなわち、きちんと名前が付いており適切な手段でアクセスできる状態にすると、プログラムをとても作りやすくなります。
リソースは「Web上に存在する情報」という抽象的な概念です。
サーバーとクライアントの間で、実際にリソースをやり取りするときには、何らかの具体的なデータを送信し合います。
サーバーとクライアントの間でやり取りするデータのことを 「リソースの表現」(Resource Representation) と呼びます。
1つのリソースは複数の表現を持てます。
例えば、天気予報リソースは、HTML形式はもちろん、テキスト形式でもPDFでも画像でも表現できます。
リソースの複数の表現に個別のURIを与えてもいいですし、HTTPの仕組みを使えば、1つのURIで複数の表現を返すこともできます。
また、リソースには状態があります。
時間の経過に従って、リソースの状態が変化すると、その表現も変化します。
天気予報の例で言えば、現在の天気予報が「晴れ」であったとしても、数時間後には「曇り」に状態が変化しているかもしれません。
引用元: 「Webを支える技術 -HTTP、URI、HTML、そしてREST」

引用にあるとおり、RESTにおける重要概念の1つに「リソース」(Resource)があります。
Web上の無数のリソースは、それぞれURIで一意の名前(識別子)を持つようになっており、URIを使うことで、プログラムは、リソースに簡単にアクセスできるわけです。

また、RESTの根幹の1つである クライアント/サーバー(Client/Server)「リソース」(Resource) をやり取りする際のデータのことを 「リソースの表現」(Resource Representation) と呼びます。
この「リソースの表現」は、APIの返却の表現形式をイメージしてもらうとわかりやすいと思います。
リクエストに対する返却データは、HTMLやJSON、XMLなど、いろいろなリソース表現ができるということを意味します。

まとめると、RESTにおいて「リソース」(Resource)が重要なのは、リソースのやり取りに重点をおいているからだと言えます。
後述しますが「REST」から発展して 「リソース指向アーキテクチャ」(Resource Oriented Architecture、通称:ROA) という設計思想が提唱されているぐらい、RESTにとって「リソース」という概念は重要なものです。

URIとURL、URNについては、こちらの記事の説明がわかりやすいです👀✨
https://www.geekly.co.jp/column/cat-webgame/1911_012/

RESTという略称の意味についての考察

ここで、RESTという略称の意味についての個人的な考察をさせてください。
「REST」 は「 REpresentational State Transfer 」(リプレゼンテーショナル・ステイト・トランスファー)の略になります。
勘違いしやすいポイントとして、4つの言葉の頭文字ではなく、3つの言葉の頭文字から取った名称であることがあります。

「REST」 を愚直に日本語に直すと 「状態を具体的に表現したやり取り」 のような意味合いになります。
ただ、これだけだと、主語がありません。。。
つまり「何の状態を表現して、やり取りするのか?」ということです。
そして、この「何の状態を表現して、やり取りするのか?」というと、それは「リソース」(Resource)になります。

リソースは「Web上に存在する情報」という抽象的な概念です。
サーバーとクライアントの間で、実際にリソースをやり取りするときには、何らかの具体的なデータを送信し合います。
サーバーとクライアントの間でやり取りするデータのことを 「リソースの表現」(Resource Representation) と呼びます。

という一文が先ほど紹介した「リソース」(Resource)と「URI」の説明にありました。
この説明から伺えることも含めてまとめると、
「REST」 の日本語訳は 「リソースの状態を具体的に表現したやり取り」 だと言えそうです。
つまり「Resource Representational State Transfer」のような意味合いで、RESTという略語を考案したのでは?
と考察できます。
また、そのことから 「REST」RE の部分は、Resource Representation(「リソースの表現」)の 2つのRE の意味なのでは?
と個人的には思っています。。。🧐

RESTの条件は、4原則か? それとも6原則か?

RESTの条件として、4原則からなるという記事が多数ありましたが。。。
私が読んでいた「Webを支える技術 -HTTP、URI、HTML、そしてREST」では、6つのアーキテクチャスタイルを組み合わせた複合的なアーキテクチャスタイルであると定義されていました。。。🥺
いったい、どっちが正解なのか。。。と途方に暮れていたときに、次の記事に出会いました😭🌟

https://miraitranslate-tech.hatenablog.jp/entry/rest-and-roa

内容を要約すると、

  • RESTが発表された論文や、「Webを支える技術 -HTTP、URI、HTML、そしてREST」では、 RESTは6つのアーキテクチャスタイルを組み合わせた複合的なアーキテクチャスタイル であると定義されていました。
    1. Client-Server(クライアント-サーバー)
    2. Stateless(ステートレス)
    3. Cache(キャッシュ)
    4. Uniform Interface(統一したインターフェース)
    5. Layered System(階層システム)
    6. Code-On-Demand(オンデマンドのコード)
  • その後、「RESTful Web Services」という書籍にて、提唱された 「リソース指向アーキテクチャ」(ROA)の4つの特性 が、RESTの「4つの原則」として普及したのではないかという考察です。
    1. Statelessness(ステートレス性)
    2. Uniform Interface(統一インターフェース)
    3. Addressability(アドレス可能性)
    4. Connectedness(接続性)
  • REST をガイドラインとしてまとめ、それに基づく設計思想として、ROA(リソース指向アーキテクチャ)が提唱されています。

というような内容でした👀
RESTを構成する6つのアーキテクチャスタイルと、リソース指向アーキテクチャ(ROA)と、ROAの4つの特性については、この後のセクションで解説します。

RESTを構成する6つのアーキテクチャスタイル

RESTは、6つのアーキテクチャスタイルを組み合わせた複合的なアーキテクチャスタイルです。
RESTの6つの条件に関して、まとめると次のとおりです。

1. Client/Server(クライアント/サーバー)

クライアントと、サーバーが通信するアーキテクチャスタイルのことです。
つまり、クライアントはサーバーにリクエストを送り、サーバーはレスポンスでリソースを返すという関係性です。

このアーキテクチャスタイルには、次のようなメリットがあります。

  1. クライアント/サーバーと処理を分離することで、クライアントをマルツプラットフォームにできる
  2. クライアントとサーバーは依存することなく独立し、お互い影響なく改修ができる
  3. クライアント(画面UI)とサーバー(データ)で関心を分離できる。
  4. 複数のサーバーを組み合わせて、冗長化することで、可用性を上げられます。

2. Stateless(ステートレス)

クライアント・アプリケーションに対する、サーバーのStateless(ステートレス)なアーキテクチャスタイルを指します。
Stateless(ステートレス)とは、サーバー側がクライアント・アプリケーションの状態(State)を保持・管理しないことを意味します。
つまり、サーバーでは、リソースをクライアントに返した後は、保持・管理せずに解放します。

このアーキテクチャスタイルには、次のようなメリットがあります。

  1. 前の状態は保持せず、それぞれのリクエストが独立して成立している
  2. サーバーに保持されているコンテキスト情報は使わない(サーバーセッションは使わない)

3. Cache(キャッシュ)

Cache(キャッシュ)は、リソースの鮮度に基づいて、一度取得したリソースをクライアント側で使い回す方式です。

このアーキテクチャスタイルには、次のようなメリットがあります。

  1. サーバーとクライアント側での通信の処理時間を減らすことができる。
  2. リソースの読み込み速度が向上する。
  3. キャッシュによる速度向上によって、ユーザー体験が向上する。

4. Uniform Interface(統一インターフェース)

Uniform Interface(統一インターフェース)とは、URIで示したリソースに対する操作を、統一した限定的なインターフェースで行うアーキテクチャスタイルのことです。

例えば、HTTP1.1で考えると、次のような統一インターフェース(制約)があります。

  1. HTTPプロトコルのメソッド(GET,POST,PUT,DELETEなど8個のメソッド)だけを用いて、データ操作を可能にする。
  2. HTTPプロトコルのメソッドで、CRUDを表現する。

このアーキテクチャスタイルには、次のようなメリットがあります。

  1. 同じリソースに対するAPIアクセスが、すべて同じ形式で統一されている
    • 一意なURIで統一されている
    • 一意なURIで、CRUD処理がすべて可能である状態
    • 例えば、/usersで考えると。。。
      • GET通信: User情報・取得
      • POST通信: User新規作成
      • PUT通信: User情報・更新
      • DELETE通信: User削除
  2. URIへの操作(GETやPOST)の方法を統一することで、全体構成をシンプルにすることができる。
    • HTTPメソッドでの操作以外は受け付けない
    • インターフェースに対して、一定の制約を敷くことで、全体構成がシンプルになる。

5. Layered System(階層システム)

Layered System(階層システム)とは、その名の通り、レイヤー構成されたアーキテクチャスタイルのことです。
例えば、Client/Server(クライアント/サーバー)の間に、ロード・バランサー(Load Balancer)を設置して負荷分散したり、プロキシ(Proxy)を設置してアクセス制限をしたりなどがあります。
他にも、リクエストを受けるレイヤー、応答を返すレイヤー、セキュリティー処理を行うレイヤーに分けるなどの手法も考えられます。
上記の事例のように、各レイヤーは特定の機能と役割を持っており、各レイヤーは、独立しながら相互作用を有しています。
複数のレイヤーが独立しつつ相互連携して、アーキテクチャを構築することで、高い拡張性のあるモジュール化されたアプリケーションを作成することができるのです。

このアーキテクチャスタイルには、次のようなメリットがあります。

  1. クライアント側からすれば、同じインターフェースで接続できる
  2. サービスの進化に合わせてシステムをアーキテクチャの内外に自由に出し入れできる
  3. レガシーシステムをカプセル化することもできる
  4. モジュール間を疎結合に保つことで、柔軟性と寿命が向上します。
  5. 各々の役割を独立させることで、再利用生を上げることができる
  6. プロキシレイヤーなどで外部からの攻撃を阻止し、実際のサーバーアーキテクチャへの侵入を防ぐなど、セキュリティ面でのメリットもある。
  7. 複数のレイヤーを持つことで、攻撃に晒される範囲や、可能性を最小化できる

改装システムの説明は、こちらのページの解説が丁寧で、おすすめです🌟

6. Code-On-Demand(オンデマンドのコード)

Code-On-Demand(オンデマンドのコード)とは、プログラムコードをサーバーからダウンロードして、クライアント側でそれを実行するアーキテクチャスタイルです。
また、こちらのアーキテクチャスタイルは、唯一のオプショナルな制約になっています。

コードオンデマンドは、6つの制約のうちで最も知られておらず、唯一のオプショナルな制約です。
コードやアプレットをAPI経由で送信しアプリケーション上で動かせるようにする、という制約です。
これにより、独自のコーディングに依存しない、スマートなアプリケーションが作成できます。
引用元: 『REST API』とは

このアーキテクチャスタイルには、次のようなメリットがあります。

  1. コードオンデマンドを組み込むことで、リリース済みのクライアントに対してサーバー主導で機能追加をすることができる
  2. クライアント側に処理の実装を寄せるので、サーバーへの負荷を下げることができる。

リソース指向アーキテクチャ(ROA)と、ROAの4つの特性

先述のように、「REST」から発展して 「リソース指向アーキテクチャ」(Resource Oriented Architecture、略称:ROA) という設計思想が出てきました。
ROAは、名前の通り 「リソース」 に重点を置いたアーキテクチャで、RESTful な設計思想です。
リソースは ROA だけでなく REST において最も重要な概念であり、リソースとは、サービスが提供する「もの」を指します。

RESTと似ている、ROAが提唱された理由に関しては、次の内容がわかりやすいので、引用します。

ROA は RESTful の定義そのものであるようにも受け取れますが、あえて「リソース指向アーキテクチャ」と名付けたのには理由があるようです。
「Restful Web Services」によると、REST には標準仕様がないことから慣習で補われた部分も多く、「RESTful を定義しよう」とすると議論が発散してしまう恐れがあるため、別の名前を付けることにしたとのことです。
引用元: 今さら聞けない REST とリソース指向

つまり、RESTをより標準仕様のように、実践しやすいガイドラインのような形で、定義したのが、ROAだと言えそうです。

この「リソース指向アーキテクチャ」(ROA)では、次の4つの特性を備えるべきとされています。

  1. アドレス可能性(Addressability)
  2. ステートレス性(Statelessness)
  3. 統一インターフェース(Uniformed Interface)
  4. 接続性(Connectedness)

それぞれ、この後、解説します。

1. アドレス可能性(Addressability)

アドレス可能性とは、リソースを URI で一意に識別して、API としてアクセス可能であることを指します。
つまり、URIを通じて、リソースを取得する簡単にアクセスできる状態になっていることを意味します。
例えば、アプリケーションがデータをリソースとして公開する場合、そのアプリケーションのそのリソースはアドレス可能となります。
リソースはURIを通じて提供されるため、アドレス可能なアプリケーションは提供可能な情報ごとにURIを公開します。
この特性によって、プログラムから接続できるようになり、分散システムを構成することが可能になります。
この特性がない場合、リソースにアクセスできないなど、API としての価値が成り立っていないため、最も基本的な特性となります。

2. ステートレス性(Statelessness)

ステートレス性は、すべてのリクエストが個別に処理され、 リクエスト間の依存性がない という特性を指します。
つまり、ステートレス(Statelessness)なAPIでは、 Stateを保持せず「やりとりが1回ごとに完結する」 ようになっています。
この特性によって、アプリケーションの拡張が容易になり、リトライなどの対策も取れるため、システムとしての信頼性が高まります。
この特性がない場合、サーバ側で状態を維持管理することを意味するため、拡張性がなく不安定なシステムになってしまいます。

3. 統一インターフェース(Uniformed Interface)

統一インターフェースは、すべてのサービスが HTTP のインターフェースを同じ方法で使用するという特性を指します。
この特性によって、サービスが変わったとしても、統一的なインターフェースで、同じようにやりとりが可能になります。
つまり、「どのリソースであっても GET は読み取り・取得を意味する」という統一性を持たせることで、よりシンプルに API を表現することができます。

4. 接続性(Connectedness)

接続性は、リソースに別のリソースへのリンクを含めて接続することができるという特性を指します。
従来のWebが使いやすいのは、リソースどうしが適切に接続されているからだと言えます。
この特性によって、関連するリソースにアクセスすることが可能になります。

ROAに関する参考記事

リソース指向アーキテクチャ(ROA)については、次の2つの記事がわかりやすくまとまっています。
https://miraitranslate-tech.hatenablog.jp/entry/rest-and-roa

https://qiita.com/NagaokaKenichi/items/0f3a55e422d5cc9f1b9c

(おまけ)RESTful API のfulとは何か?

RESTについては、理解しましたが、RESTful APIのfulとは何なのか?
こんな疑問を抱いたら、ちょうど、その疑問を解決してくれる記事があったので引用します。

RESTfulのful とは?
REST(Representational State Transfer)は、ソフトウェアアーキテクチャのスタイルの一つ。
ロイ・フィールディングの論文で述べられているように、RESTは基本的にWebの既存の技術とプロトコルを利用した「アーキテクチャスタイル」です。
RESTfulは、通常、そのようなアーキテクチャを実装したWebサービス、という意味で使用されます。
つまり、RESTはアーキテクチャで、RESTfulは形容詞。RESTなアーキテクチャ性があること、これすなわち、RESTful。
Beautyは美で Beautiful は美しい。
RESTful APIは「REST的な、REST性なAPI」、REST APIは「REST(というアーキテクチャの)API」ということ
引用元: RESTful APIとは何なのかとは何なのか - RESTfulのfulとは何なのか

つまり、RESTはアーキテクチャで、RESTfulは形容詞ということ。

Beautyは美で Beautiful は美しい。

とあるとおり、RESTful API とは「RESTアーキテクチャなAPI」(REST的なAPI)という意味でした。。。🥺

https://qiita.com/e99h2121/items/4409af3879e8638b8200

Web API 設計 〜実践編〜

実践編は、こちらです👀✨
https://zenn.dev/aiq_dev/articles/46850363412d95

まとめ・感想

RESTについて、体系的にまとめられて、学びが多かったです。
「Webを支える技術 -HTTP、URI、HTML、そしてREST」は、名著なので、おすすめです🌟
また、原著は読んでいませんがROAについて記載のある「RESTful Webサービス」にも興味が湧きました🔥

Xやっております!よかったらフォローしてください🐱
https://twitter.com/masanyon1212

注意事項

この記事は、AIQ 株式会社の社員による個人の見解であり、所属する組織の公式見解ではありません。

求む、冒険者!

AIQ株式会社では、一緒に働いてくれるエンジニアを絶賛、募集しております🐱🐹✨

詳しくは、Wantedly (https://www.wantedly.com/companies/aiqlab)を見てみてください。

参考・引用

https://gihyo.jp/book/2010/978-4-7741-4204-3

https://e-words.jp/w/REST.html

https://e-words.jp/w/URI.html

https://qiita.com/TakahiRoyte/items/949f4e88caecb02119aa

https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

https://www.mulesoft.com/jp/resources/api/what-is-rest-api-design

https://xtech.nikkei.com/atcl/nxt/column/18/00138/092100882/

https://miraitranslate-tech.hatenablog.jp/entry/rest-and-roa

https://qiita.com/NagaokaKenichi/items/0f3a55e422d5cc9f1b9c

https://ics.uci.edu/~fielding/pubs/dissertation/top.htm

https://qiita.com/e99h2121/items/4409af3879e8638b8200

https://zenn.dev/manase/scraps/0a7a0e51528daf

AIQ Tech Blog (有志)

Discussion