Web APIの設計、開発、運用についての解説書。本書ではAPIをどのように設計し運用すればより効果的なのか、ありがちな罠や落とし穴を避けるにはどういう点に気をつけなければいけないのかを明らかにします。ターゲットは、URIにアクセスするとXMLやJSONなどのデータが返ってくるシンプルなタイプ―XML over HTTP方式やJSON over HTTP方式―のAPIです。

自分はここ2年間くらいは専らモバイルアプリエンジニアという立ち位置なので、どちらかと言うと「用意してもらったWeb APIを叩いてビューを作る」方の立場なのだけど、Web APIのユーザーとしても使い易いAPI、イケてるAPIって矢張りあるよなーと。

「何でこのAPIは使いづらいんだろう」という日々感じているモヤモヤがすっきりと理解・整理できました。良いエンドポイントの原則として挙げられている「覚えやすく、どんな機能を持つURIなのかがひと目でわかる」も、「これだ」と思えるワンフレーズで非常に良いです。2015年現在の「世に出して恥ずかしくない」Web API設計を考える時に、ベストに近いヒントがもらえる本と言えます。

方針として

仕様が決まっているものに関しては仕様に従う

仕様が存在していないものに関してはデファクトスタンダードに従う

と明示されており、Amazon、Facebook、Foursquare、Tumblr、TwitterといったWeb APIのパワーをてこに成長したメガサービスではどんな実装をしているかを各所で実装例として引いており、とても参考になります。日本のウェブサービスでも楽天、ぐるなび、リクルートなどの有名処がサンプルとして度々登場しています。各サービスで「性別」をどう表現しているか（「sex」 or 「gender」）のような例ひとつ取っても膨大なサンプルが引いてあって面白い。

本書の冒頭で、執筆自体は2012年くらいから取り掛かっていたという下りがありますが、まさにその頃に仕様やデファクトスタンダードとして確立したトピックも網羅されており、「あ、これ知らんかった」という概念も幾つか見付かりました。

レスポンスフォーマットとしてはJSONが必須でXMLがオプショナル。
- JSONのトップレベルは配列よりもオブジェクトの方がベター。
- レスポンスボディで扱う日付フォーマットはRFC 3339かUnixタイムスタンプを選んでおけば間違いない。ただしHTTPヘッダでは使えないのでRFC1123を用いる。
JSONPはサポートする特別な事情が無ければ、サポートしなくて良い。
- サポートする場合は、エンベロープとしてのHTTP表現が使えなくなってしまうので、ヘッダーとして返すべきメタ情報をJSONで表現する事になる。
リソースの更新にはPUTメソッドの他にPATCHメソッドを用いる事もできる。
- 知らなかった。
リクエスト制限値を超えている時にステータスコード429を、サービス停止中をステータスコード503を返すようなケースでは、「Retry-After」ヘッダで何秒後には復活するかという情報を付与できる。
- これも知らなかった。
APIバージョンはセマンティック・バージョニングにおける「メジャーバージョン」のみを使い、マイナー相当の更新は同一メジャーバージョンのまま提供する。
- そもそもWeb APIではバージョンアップは最後の手段であり、同じまま続ける方が良い。
- 大規模バージョンアップのケーススタディとして、TwitterのBlackoutテストやアナウンスを紹介している。

必ずしも「こうした方が良い」と言い切れない判断に迷うようなトピックの場合も、多くのメガサービスでの事例を引いた上で、最後に「著者はこう考える」と述べてあり、RESTfulなWeb APIを目指す理想と、泥臭いウェブサービス提供側の現実との最適解を考える上で良いヒントになっている。

書籍のボリュームも200ページ弱で、すぐ読める割に扱っている内容は濃密なので、おすすめです。個人的にはモバイルアプリをクライアントとした場合の設計（何度もHTTPリクエストさせないためにまとめるAPIを立てる、みたいな話）については、もう少し掘り下げて欲しかったかな。しかしHTTP 1.1 + JSON時代の決定版と言って良く、今後3年間はこの本に書かれた考え方で大丈夫そう。

[ツッコミを入れる]