はじめに
イベントリンク : RESTful WEB APIs読書会 第4回
開催日時 : 2020/01/24
開催場所 : 弁護士ドットコム株式会社
ハッシュタグ : #RWABook
BEARフレームワークの作者でもある @koriym さんを中心に、RESTful Web APIs を解説・ディスカッションしながら読み進めていく会です。
また懇親会を通して、議論を深めていくようなコミュニティでもあります。
本記事は、そのRESTful WEB APIs読書会（以下、RWABook）の参加レポートであり、正しいRESTに対する知識の共有とRWABookへ興味を持ってもらうことを目的とします。
これまでの復習
前回までで、Chapter2. A Simple APIまでが終了しています。
今回で第4回目の開催となりますが、初参加の方も多くいたのでChapter1.からの振り返りを行いました。
振り返りを含め、今回読み進めたChapter3. Resource and Representationまでのまとめを次で述べていきます。
Chapter0. Motivation
@koriym さんが考えるRWABookに対するモチベーションについて。
なぜこのような集まりをしているのか、それは時間とともに進化する有用なREST APIを設計するために必要なものであり、これこそがRESTの本質であるからだ。
前述したRESTful Web APIsには、今から本を読むのに関して必要な知識等について書いてある。その言葉について本で説明をしていく（ハイパーメディアが表現を一貫したAPIに結びつける方法を理解する）。
キーパーソン
Roy T. Fielding
RESTの定義についての論文を書いた人。（彼の書いた論文は次の通り。https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm）
Certainly more deliberate in the sense that they start out with talking about difference between my REST and whatever they are calling a REST API. Just as I have a slide that says there is no such thing as a REST API, only RESTful applications that use APIs. They understand.
— Roy T. Fielding (@fielding) March 20, 2019
REST APIのようなものはない、APIを使ったRESTfulなアプリケーションは存在する。とRoy T. Fieldingは言っており、「色んな種類のRESTが存在する」といったがよく記事で書かれているが、それは誤りである。
Tim Bray
XMLの生みの親。
ongoing by Tim Bray · Post-REST この記事では、RESTfulで出来ていないものについての説明。レイテンシやgRPCやGraphQLなどについて言及。 特にRPCについて、gRPCが失敗してきた歴史を見てきたからRPCについては懐疑的だ。 クライアントとサーバーが密結合したAPIはうまくいかない。
RESTlessnessに打ち勝つ
RESTlessnessに打ち勝つこの記事ではRESTはいらないんじゃないかというアイデアに対して書かれた記事。
GraphQLやgRPC，Apache Kafkaといった新しいAPIプロトコルが，RESTに基づいたHTTP APIに代わるものとして人気を集めています。この記事では，RESTパラダイムの長所は1対1のプロトコル比較では表現できない，という主張を展開します。RESTの代わりを探すのではなく，ソフトウェアエンジニア産業は，成熟したRESTエコシステムを基盤として，新たなプロトコルの技術的長所を探求する手段を模索するべきです。
つまり技術というものは、新しいもので置き換えるのではなく "漸進的"であるべきであるということ
しかし現実には、ソフトウェアエンジニアリングの進化は通常、層を成して起こるものです。新たな技術革新が、それに続く新たなイノベーションの基礎を築くのです。
既存を崩して全くの新しいものを作るのはうまくいかない。失敗してきたことを分析してみると多くの場合がこのことが理由の一つである。
Chapter1. Surfing the Web
看板を見つけた利用者はURLに対してアクセスをするが、URLを知ることだけでそれ以外は何も知らなくていい。
Resources and Representation リソースと表現
HTTPリクエストがウェブサーバーへ送られてくる。専門用語ではURLはリソースである。
サーバーはしばしばHTML（ときには画像など）のレスポンスを送ってくる。
それが何のドキュメントであろうとも、リソースの"表現"と私たちは呼ぶ。
Addressability アドレス可能性
独立したURLは一つまたは一つの表現である。
The principle of addressability just says that every resource should have its own URL.
アドレス可能性の原則は、それぞれのリソースは独自のURLを持っていることを示している。
Short Sessions 短いセッション
サーバーに送った後はクライアントは何を送ったかなど興味を持たない。ただ情報を返すだけでなく、次に何をすべきかという情報を含めている。
この原則は、時々ステートレスとも呼ばれている。ステートレスはサーバーがクライアントが入っているものの状態を気にしないという事実になっている。
Self-Descriptive Message 自己記述的メッセージ
見たい情報だけでなく次に何をするかまでを書いている。そういう選択肢がある。
補足
HTTPに慣れすぎてレスポンスが返ると、サーバーはクライアントのことなんて知らないのは当たり前になってきている。SSHなどずっと接続し続けるようなものは常にサーバーは状態を知って置かなければならない。誰が何を見るかなんて興味ない。
Webだと一つのページを開いたまま何ヶ月も放置したあとに、そのままリンクを開いたら開くことが出来る。 実際に何があるかは訪れてみないと分からない。連想はわかるが実際の中身はアクセスしないと分からない。
ユーザーの頭の中にはPOSTできそう？とかのメンタルモデルが出来る。一つ何かをすることでメンタルモデルとして形成されるためサイトマップを見ずとも伝えることが出来る。
Standardized Methods 標準化メソッド
独自のメソッドを使用するのではなく、GETなどHTTPプロトコルで定められている標準メソッドを使用する
State 状態（アプリケーション状態とリソース状態）
サーバーはアプリケーション状態を知らない。それをアプリケーションが見ている状態がアプリケーション状態。
ルートは同じでも2つ返していたメッセージが3つのメッセージを返すようになった。これはリソース状態。イメージとしてはDBの中身が変わってリソースが変わるといったこと。
Roy T. Fielding はREST全体を構成するものをアプリケーションと呼んでいる。その中の状態であると捉えると近い。
Connnectedness 接続性
HATEOAS : アプリケーション状態としてのハイパーメディア（hypermedia as the engine of application state hypermedia）は次に繋がるもの。ハイパーメディア制約のことを接続性と言い換えている。
Web APIs Behind the Web
- 今のWebAPIは人間が読めるドキュメンテーションを説明出来る
- リソースとリソースはお互いを知らない
- 新しいAPIを使うためにはそれぞれ書かないといけないが、ウェブサイトを使用するためにはカスタムソフトウェアを書く必要はない
- APIが変わるとカスタムAPIクライアントは壊れてしまう
The Semantic Challenge
どうやったらマシンが理解することが出来るか。そういったギャップ（セマンティックギャップ）を埋めるようなこと。 人間だったら簡単に理解することが出来る。
Chapter2. A Simple API
JSON
- key+value
- 何もかもつけることが出来るから、全てを説明する必要がある
Collection+JSON
- collection（集合）を知るためのJSONの拡張
- メディアタイプがこれだとなにかの集合を表すかを知ることが出来る
- それがなにかを説明するようなリンクがつく
Librated by Constraints
RESTfulな設計の直感に反する教訓の一つは、制約によって自由になることが出来る。（HTTPのGETメソッドの安全性の制約など）
アプリケーションセマンティックはセマンティックギャップを作る
似たようなブログやレシピサイトがあったとしても、それが何なのかをいちいち説明しないといけない。
Chapter3. Resources and Representations
この章ではWWWアーキテクチャについて述べられている。
Architecture of the World Wide Web, Volume One が勧告されている内容。
URIに意味を含めるのはとても魅力的な内容だが、それは特に意味がないと言ったことが書かれている。（よくあるURLから推測する出来るものがベストプラクティスという記事とは真逆の考え）
リソースそのものではなくて表現はリソースの状態を表している。
XMLかもしれないしCSVかもしれないし、それはアプリケーションによって知ればよい。
表現は送ることが出来る。見方によってものの見方は変わってくる。
同一のものなのにメディアタイプが違えば見方が変わる。
表現は行ったり来たり転送される。クライアントからサーバーに支持を送るときにも表現を使う。
POST message=Test&Submit=POST のようなもののやり取り。
複数のゲームをサポートする2つの戦略がある、同一のものだからメディアタイプでわけるのか、それとものURLを分けるのか。
- コンテントネゴシエーション or URL
- リクエストヘッダに書いてあるからそれを返す
The Protocol Semantics of HTTP
- GET : リソースそのものではなくリソースの表現に基づいてを取得する
- DELETE : リソースを破壊する
- POST : リソースの下につくる URLが決まっていない
- PUT : URLが決まっているものに対しての更新、一番下への追加。リソースの状態を変えてしまう、なければ作ってしまう
- HEAD : ヘッダーだけを取得して表現を取得しない
- OPTIONS : レスポンスするHTTPメソッドを返す
- BEAR.Sundayはそれをサポート。クロスオリジンのときなどに使われる。
- PATCH : 与えられた表現に基づいて、リソースの状態の一部を変更する
- LINK : リソースに他のリソースを接続する
- UNLINK : リソースと他のリソースとの接続を破壊する
冪等性
何回行っても同じ結果になること
GET、DELETEは冪等（DELETEは404になるが結果としてリソースが消えているという事実は変わらない）
POST-to-append
POSTはリソースへのPOSTリクエストを送信することと、その下に新しいリソースを作成する"POST-to-append"である。
Overloaded POST
もう一つのPOST
なんでもアリなPOST。HTMLの中ではGETかPOSTしか出来ない。ということはありとあらゆることをPOSTでしている…。
Which Methods Should To Use?
どのメソッドを使うべきか？
GET POST PUT DELETE PATCHがあれば十分だと本では記述されている。
CRUDとHTTPメソッドをマッピングするようなものではない。マッピングだと思いすぎると本質とは違ってくるので注意。
おわりに
次回は2月14日 19:30〜（19:00開場）（金）@弁護士ドットコム株式会社にて、RESTful WEB APIs読書会 第5回を行います。
申し込みはconnpassの下記リンクからお願いいたします。
RESTful WEB APIs読書会 第5回
次回はChapter4. Hypermediaから読み進めていきます。