アプリ開発者なら書籍「Web API: The Good Parts」は読んでおくべき
最近のアプリ開発においてクライアントサイドだけで完結するようなものはかなり少なくなってきたと思います。 おそらく何らかのAPIを直接もしくはSDK経由で呼び出すことがほとんどではないでしょうか。 そういった背景がある以上、すぐれたWeb APIがどうあるべきかというのはサーバサイドを担当するエンジニアだけでなく、 クライアントサイドを担当するエンジニアであっても知っておくべきでしょう。
今回読んだ「Web API: The Good Parts」はWeb APIを美しく設計する重要性、そして美しく設計するための指針を すでに公開されている様々なWebサービスのAPIを例に挙げながら、よりよい方法を提案してくれています。
個人的に印象に残っている内容をいくつか挙げておきます。
- エンドポイントの設計において重要な原則として「覚えやすく、どんな機能を持つURIなのかがひと目でわかる」こと
- RESTを意識しすぎない
- REST APIの設計レベルにはREST LEVEL3(HATEOASの概念の導入)まである
- 仕様が存在していないものに関してはデファクトスタンダードに従う
- レスポンスデータの設計において一部例外はあるがエンベロープは不要(理由としてはHTTPプロトコルというエンベロープがあるから)
- レスポンスデータはなるべくフラットにすべきだけど階層化したほうが絶対によい場合は階層化もあり
- エラー時は適切なステータスコードを返し、エラーの詳細はレスポンスボディにデータを入れる方法がクライアントの利便性が高い
- 配列データを返す場合、そのまま配列として返すよりオブジェクトに配列を包んでキーをつけて返す方がおすすめ
- HTTPの仕様をしっかり理解してなるべくそれを活用する（たとえば正しいステータスコードを返すなど）
- APIのバージョン管理はURIにバージョンを入れるタイプを推奨している(Twitter、Facebook、Tumblrなどが採用している)
Web APIを提供する側、使う側ともにすぐれた設計を共通認識として持つことで 開発の効率化につながりますし、Web APIを公開した際に変な設計をさらして恥をかくこともなくなりますw
正直もっと早く読んでおくべき本でした。
本書は全体で224ページと内容はコンパクトにまとまっており、 全てを読むのにさほど時間もかからないので是非一読してみることをお勧めします。
