REST APIの原則って結局何個あるの
寺田 明日香
こんにちは、IT業界ビギナーのあすりんです。この初心者の初心者による初心者のためのシリーズもなんと４本目となりました。そろそろ初心者って外したほうがいいのかもしれないと思いつつ、新しい言葉に出会うたび、まだ見ぬ自分を発見しているのでもうしばらくは初心者でいようと思います。
さて、今回はREST APIを取り上げていきます。
目次
REST APIの原則は６個ある
それぞれどういう意味を持ってるの
REST APIに代わる新しい技術があるって聞いたけどどういうこと？
WEB APIを理解する上で欠かせないのがRESTという設計思想だ…！
REST APIの原則（制約）は６個ある
RESTful API（レストフルエーピーアイ）、またはREST API（レストエーピーアイ）というのは、APIの構築方法を定義する設計思想、と言われています。もうこの時点で私の頭はパンクしそうです。
設計方法ではなく、設計思想、というところがミソ。
APIを構築する時に従うべき考え方の方向性、という感じです。あくまで思想なので、設計するエンジニアにとっては説明が大まかすぎてこれだけでは設計できないらしい（仕様が確定しない）です。
さて少しWEBを調べてみると、その思想の軸となる原則（または制約）と呼ばれるものが４〜６個（！）存在します。
そしてどのセットも絶妙に違う。
本来であればここで一次資料にあたるべきですが、ちょっとここに時間をかけてもいられないので、一次資料にあたって書かれた先人のWEB資料を引かせていただきます。こちらっ。
”日本において「REST の４つの原則」とされることが多い以下の項目は『RESTful Webサービス』で説明されている『リソース指向アーキテクチャの４つの主な特徴』です。
アドレス可能性(Addressability)
ステートレス性(Stateless)
接続性(Connectability)
統一インターフェース(Uniform Interface)
「すべての Web サービス設計者に捧ぐ「RESTful って結局なんなんだ」 https://zenn.dev/wsuzume/articles/280ba652dc4fc7 "
こちらにもあるように、現在日本でREST APIの4つの原則、と呼ばれているものはもともと「リソース指向アーキテクチャの特徴」とされていたもののよう。
では6つの方の根拠ってなんなの？ってなるんですが、上記の記事によるとそれがRoy Fielding氏の一次文献にある以下の「制約」のことらしい。
６つの制約はこちら。
RESTの６つの制約
Client-Server（クライアント-サーバー）
Stateless（ステートレス）
Cache（キャッシュ）
Uniform Interface（統一したインターフェース）
Layered System（階層システム）
Code-On-Demand（オンデマンドのコード）
あ、なんかこれ見たことあるな、と思ったら、以下でIBMがほぼ同じ制約を挙げていました。
“Uniform interface
Client-server decoupling
Statelessness
Cacheability
Layered system architecture
Code on demand (optional)
https://www.ibm.com/topics/rest-apis”
一次文献に忠実に行くならこちらがいわゆるRESTの原則、ということになります。
ちなみにAWSの説明では「Client-server」が省略されて５個になっていますが、APIが基本的にクライアントとサーバーをベースに展開されるものだということを知っている手だれビギナーの私たちはこれが省略されてもRESTの説明としては特段問題ないことを理解できることでしょう！やったね。（というか、APIの説明自体がRESTをベースになされていた、という方が正しいかもしれません）
今回はこちらをベースに考えてみたいので、次に６つの制約についてみていきます。
制約はそれぞれどういう意味を持ってるの
6つの制約を細かく見ていくとそれぞれ記事にできそうなボリュームが出てしまうので、ここでは私の理解像を元に簡単に触れていきます。
あくまでイメージなので、語句の定義や使用について厳密ではないです！ご注意ください。
というのも、ほら、厳密に書くと逆によくわかんなくなっちゃうから…。
ビギナーな私たちは技術者ではないので、基本アドホックな理解のまま進んでいきます。
詳細や正確な説明については先人の素晴らしい記事や一次文献をご覧ください。最後にレファレンスも置いておきます。
Client-Server（クライアント-サーバー）
クライアントとサーバーは、それぞれ独立していなくてはならない。独立というのはどういうことかというと、コンピューターのシステムのうち、機能を提供する側を「サーバー」、実際に私たちが使うサイトなど、機能や情報を受けて利用する側を「クライアント」として分けてそれぞれ役割を分担するという事です。
クライアントは「この情報が欲しいよ」というリクエストの送信のみサーバーに対して行うことができ、サーバー側もリクエストを実行し、結果をクライアントに返すことだけを行います。
独立であることで、クライアントとサーバーそれぞれ別に開発を進めることができるというメリットがあります。
Stateless（ステートレス）
クライアント側は一回のリクエストに、作業に必要な命令は全部入れといてね、後に残しておけないから、っていうこと。サーバー側にクライアントのトークンなどリクエスト関連のデータを残さない、ということ。
ステートレスという名前の通り、やり取りの時の状態を何も残していないので、やり取りが1回ごとに完結します。クライアントがサーバーに「さっきの情報をもう一回頂戴」と問い合わせても「なんのこと？」となってしまうので、都度リクエストの際は必要な情報を全部書いてもう一回リクエストする必要がある。
Cache（キャッシュ）
とはいえデータが増えてきて負荷が増える中では許可した情報は残せる方が効率はいいよね、ということ。キャッシュとは一時的な保存領域にリクエストした結果は残すことができる仕組みです。キャッシュ済みのデータは再度リクエストして取ってくる必要がなくなるため、サイトなどで表示する場合はスピードアップに繋がります。
※キャッシュとステートレスの関係について補足
情報を残していいと言ったり残したらダメだと言ったりどっちやねんとなると思うんですが。ステートレスの項目で言う残しておけない情報というのは、問い合わせをしているクライアントに関する詳細情報（ヘッダーやトークンに載せた情報）であり、キャッシュとして残しておくのは問い合わせした結果のほう。ですので、それぞれ取り扱う情報の質が違うということで、矛盾する制約ではないとのことです。
ここからは例えですが、図書館へ行って身分証明書を使って本を借りて、その本のコピーをとって帰ってきたとします。再度図書館へ行って情報を取得する場合はもう一度身分証明書を提示しなくてはなりませんが、同じ情報であればすでにコピーが手元にあるので、そもそももう一度取得しにいく必要はありません。この時の、身分証明書がステートレスとして扱われる情報で、コピーの方がキャッシュ、というイメージです。
Uniform Interface（統一したインターフェース）
やりとりをあらかじめ決まっているお約束ごとを守って行いましょう、ということ。細かい取り決めは色々あるようですが、「リクエストはデータの取得、追加、更新、削除、どの命令か送ってね（HTTPメソッド）」や「やりとりするデータはJSON形式にしようね」といったお約束ごとを決めておくことで、やりとりを分かりやすいものにしてくれます。
みんなが約束を守ることで、ルールさえわかっちゃえばやりとりに入りやすくなるメリットがあります。以前に触れた、開発に使用するプログラム言語によらずやりとりを可能にするのもこの制約によるもの。
Layered System（階層システム）
サービスを構築する際、階層を分けた構造にすることで必要ないところは隠しておこう、ということ。必要のないところは隠すことでやりとりを単純化できるわけですね。
この辺完全に想像の世界なんですが、イメージとしては、誰でも入れる一階のエントランスに受付を置いておいて、あれ持ってきてください、って頼むと、ロボットなどがビルの中を走ってデータを持ってきてくれて、受付から渡されるという感じです。来訪者は上階へはアクセスできません。
Code-On-Demand（オンデマンドのコード）
クライアントがサーバーにリクエストを送信した際に、サーバーは通常のデータだけでなく、「実行できるコード」を返してもいいよ、ということ。
通常クライアントがデータを受け取ったあとそれを画面に表示させるには、表示させるためのコードを書かなくてはいけません。サーバーがクライアント側でデータを表示するためのコードも一緒に送ることで、クライアント側は作業を減らすことができます。
と、ここまで説明してきましたが、これはあくまでざっっっくりの理解となります。
基本は先述のIBMサイト、もしくは以下の記事の説明などで詳しく理解していただけますと幸いです。
REST APIに変わる新しい技術があるって聞いたけどどういうこと？
ここまで頑張ってREST APIを理解しようと努めてきました。
なるほど、私がWEB APIとして理解したものの根本的な特徴がここで明らかになった、という感慨があります。
ところが、一部ではGraphQLという技術が登場しているとのこと！あれ、なんかこれどっかで見た！昔やった！
→システムでいう「クエリ」ってなんなの｜GOODLOCAL.jp
先述のように、REST APIというのは設計思想。
具体的にどういう設計をするか、というのは各エンジニアに任されているのですが、そこへGraphQLというクエリ言語によって新たなやりとりの地平が切り開かれました。
どういうことかというと、この記事が正しいとすると、RESTをベースにすると、欲しい情報ごとに何度もリクエストをしなくてはいけない。でもGraphQLなら、一つのリクエストで複数の情報を得ることができる、ということのようです。
これの良い点は以下の通りです。
何回も呼び出さなくていい
1回のリクエストで複数のリソースにアクセス可能
確かに、あちこちからAPI通じてデータをもらって構築されたクライアントアプリとかだと呼び出しの手間が少ない方が動きが良さそう。
詳細な比較はこちらをご参考になさってください。
GraphQLとRESTの比較｜HASURA
https://hasura.io/learn/ja/graphql/intro-graphql/graphql-vs-rest/
GraphQLについて調べ始めるとまた記事が長くなるので、これについてはまた別途。
RESTとの違いを見比べながら頑張って理解してみたいと思います。
WEB APIを理解する上で欠かせないのがRESTという設計思想だ…！
以上つらつらと書いてきましたが、まとめるとWEB APIという便利な道具を作っていく上で、ベースになってきた思想がREST APIだった、ということのようです。
ただし、近年の増殖し続けるコール数とデータ量とをスムーズにさばいていくために、より便利にAPIは進化しているよ、という。
この世界の展開は本当に早く、私が業界へ所属するようになって３ヶ月余りの間にも状況が変わってきていてめちゃくちゃ怖い。ビギナーの私も置いていかれてはいけない。エンジニアと共に戦う準備くらいはしておかねば。
ということで次回はいよいよGraphQLについて解読を試みたいと思います。ひえ〜頑張ろ〜。
レファレンス
今回勉強させていただいた先人の記事はこちら！いつもありがとうございます。
★おすすめ★
「すべての Web サービス設計者に捧ぐ「RESTful って結局なんなんだ」｜Josh Nobus
https://zenn.dev/wsuzume/articles/280ba652dc4fc7
What is a REST API?｜IBM
https://www.ibm.com/topics/rest-apis
RESTful API とは｜AWS
https://aws.amazon.com/jp/what-is/restful-api/
REST APIを基本から理解する | MuleSoft
https://www.mulesoft.com/jp/resources/api/what-is-rest-api-design
GraphQLとRESTの比較｜HASURA
https://hasura.io/learn/ja/graphql/intro-graphql/graphql-vs-rest/
リソース指向アーキテクチャって何、という方はこちらを
今さら聞けない REST とリソース指向｜Mirai Translate
https://miraitranslate-tech.hatenablog.jp/entry/rest-and-roa
※All illustrations are illustrated by DALL-E.