RESTful#とは勉強会で公開レビューしてきました

2/22にヴァル研究所さんのオフィスで開催された「RESTful#とは勉強会13回」に公開レビュー企画のゲストとしてお呼ばれしてきましたー。

この勉強会自体は今回で13回目とそこそこ回を重ねた勉強会で、RESTful APIについてみんなで学び考える会となっているそうで。すみません、こういう勉強会があることは知ってたけど参加は初めてでした。

で、公開レビューとは何かというとヴァル研究所さんと言えば「駅すぱあと」なわけですがこの駅すぱあとのWeb版である「駅すぱあとWeb」の公開APIをRESTの観点でみんなの前でレビューするというチャレンジングな企画でした。

RESTful APIが何かについては以前に発表に使ったこのスライドを参照してもらえれば。

RESTful API 入門 from Keisuke Nishitani

さて、今回のそもそものキッカケは、この勉強会の運営にヴァル研究所の総務（！）の方が関わっているんですが、以前とある勉強会のスピーカーとして喋った際、話の中で自分がRESTおじさんだと言う話をしたところ、

「RESTの勉強会やってるんでそっちにも来てくださいよー」

「ただ行くだけじゃつまらないので公開レビューとかしますか（適当」

「じゃ駅すぱあとのAPIでやっちゃいましょー（悪ノリ」

という経緯です。

それをまさにそのAPIを作ってる部隊のマネージャーであるヴァル研究所の見川さんに快諾頂けたので実現した感じです。

当日は、前半がワークショップ形式で参加者が複数のテーブルに分かれた上で、駅すぱあとのWebAPIを実際にみんなで叩きつつAPIデザインとしていいと思うところ、改善したほうがいいと思うところをディスカッション。後半が公開レビューという形。

実際のレビューについては、思っていたより（失礼）綺麗にAPIが設計されていたのと、サービスの性質上ほぼリソースの取得（CRUDのR）のみだったこともありそれほど言うことがなかったのが正直なところ。

というわけで一般的なRESTfulなAPIデザインにおけるベストプラクティス的なものを駅すぱあとのAPIの改善点として紹介する形にした。一例として、

リソースの相関がURIパスとして表現されるのが良い
URIパスとして表現されるリソースはコレクションになるのでリソース名は複数形を使うことが多い
バージョンの指定方法について（パス/クエリ/ヘッダのどれを使うか）
似たようなリソース名があってわかりにくい、もしくは分かれている必要がない

など。

駅すぱあとのAPIをお題にこういう話をしていたんだけど、素晴らしいなと思ったのはどうしてこういうデザインになっているのですか？と聞くと見川さんからその全てに対して回答が返ってくること。パッと見ではおかしいのでは？良くないのでは？と思うようなデザインのものに対してもなぜ、どういう経緯でこの形になっているのかがちゃんと説明されるのである。これはただただ感心すると同時に見川さんのこのサービスに対する愛のようなものを感じたｗと同時に駅すぱあとの裏側みたいなものも垣間見えてそれはそれで単純に面白かったと言える。

とまあ、それなりにいい感じで終了したんだけど、当日参加者からもあがったRESTfulである必要性や、RESTの一般的なルールをどこまで守る必要があるかについて個人的な見解を述べておく。これには異論もあると思うが。

まず、RESTfulであることの必要性について。RESTfulでなければいけない必要性は全くないと考えている。RESTなんてのは所詮実装指針アーキテクチャのスタイルであり原則にしか過ぎない。一方でメリットとしても語られることが多いがRESTfulなAPIはリソース指向であるが故にWebの世界と親和性が高く、URIによってリソースを特定するという概念そのものは非常にわかりやすいと言える。例えば/booksにGETリクエストをすると本のリストが返ってきて、その中の特定のアイテム、例えばbookidが1のものを取得する場合は/books/1にGETリクエストをするというのは非常にわかりやすくないか？こういったリソース名によるURIとそれに対するCRUD操作をHTTPメソッドで表現すること、そしてリクエストの応答となるステータスコードに意味があるということがRESTの最大の特徴であると同時にそういったシンプルな分かりやすさがRESTfulなAPIの最大のメリットである。単に404が返ってくるというのはページが存在しないという意味ではなく、URIで指定されたリソースが存在しないということなのである。そういう綺麗さがRESTの魅力ではあるものの、別にRESTfulでなくてもURIとして表現されるものが何らかの一定のルールに則って利用者に分かりやすければそれはそれでいいのではないかと思う。ただし、いわゆるRESTfulなAPIでないものをRESTful APIと呼んで公開されているのは個人的にはdisりの対象である。

そして、次にいわゆるRESTfulであるAPIとしてのルールについてだが、先にも言ったとおりRESTなんてものは標準仕様でもなんでもなく実装指針アーキテクチャスタイルでしかない。数ある解説において、共通する基本的なルールはあるものの細かいところは正直なところ人によって主義主張が違うと言っていい。例えば先のバージョンの表現方法もそうだ。/v1/booksと/v2/booksという形の場合、v1のリソースセットとv2のリソースセットは別物であるという考えからだ。一方であくまでもリソースはリソースとして同一のものでありバージョンは属性情報の一つという考え方の場合、/books?version=2といったクエリによる指定になる。加えて、リソース名の設計指針としてよく言われるリソース名は複数形で表現すべき、や複数の単語で構成されるリソース名は"-"で区切るべき、とか小文字が望ましいとかそういったのは瑣末なことであり別にどうでもいいと思ってる。勉強会での川村さんの発言にもあったが「全体で揃っていればいい」と思う。もちろん新たに設計する場合、基本的にそういったルールには則る形にはするが。

とまあ、何が言いたいかというとRESTは綺麗なAPIデザインをする上ではとてもいい考え方だがそれに引っ張られすぎるのは本末転倒であるなのでそこそこにしてもっと本質的なことに時間割こうよ、ということである。

そうは言っても僕はRESTオジサンだし、REST原理主義者とも言えるのでREST的に美しくないAPIデザインは認めないんだがｗ矛盾していると言われてもいい。

とにもかくにも関係者の皆様、こういう機会を頂きありがとうございました。

* 当初、実装指針と言った部分が誤解を生む表現だったので修正しました