最近はWeb APIの開発ばかりやってますが、設計方法については『Webを支える技術』を読んだ程度でした。
Web API設計の基本はRESTなので、『Webを支える技術』はとてもためになりますが、もう少し実践よりの本も、ということで『Web API: The Good Parts』を読んでみました。
実践よりとはいっても、『Web API: The Good Parts』には具体的なWeb APIの実装は出てきません。
それよりも一段上の、「Web APIをどう設計すべきか」という点に焦点が絞られています。
また、「Good Parts」シリーズらしく、著者の独自の観点で練り上げられたベストプラクティスが網羅されています。
なお、出版は2014年ということで、gRPCのような新しめの概念には触れられていません。
Web APIチェックリスト
本書で一番良いと思ったのは、巻末の「Web APIチェックリスト」です。
ここには、本書で紹介されているベストプラクティスのうち、特に重要なものがリストアップされています。
一例を挙げると以下のような項目です。
- URIが短く入力しやすくなっているか
- URIが人間が読んで理解できるようになっているか
このリストをそのまま使ってもいいですし、自分たちでAPIの設計指針を定める場合にも、このリストをベースに作れば楽ができそうです。
標準を尊重する
本書の基本的な哲学は以下の二文で表されます。
- 仕様が決まっているものに関しては仕様に従う
- 仕様が存在していないものに関してはデファクトスタンダードに従う
「HTTPの仕様を活かしてWeb APIを作る」ということですね。
設計に迷ったときはまず仕様、仕様がないときはデファクトスタンダードを調べることが大切です。
具体例に基づいた解説
フィールド名をキャメルケースにするかスネークケースにするか、といった、標準が存在せず設計に迷う場面では、Twitter、Facebook等の大手Webサービスを調査して「デファクトスタンダード」を探っています。
この調査結果が載っているのもありがたいところ。
REST LEVELとHATEOAS
「どのくらいまでRESTに準拠しているか」を示すREST LEVELという概念があります。
- REST LEVEL0 – HTTPを使っている
- REST LEVEL1 – リソース概念の導入
- REST LEVEL2 – HTTPの動詞の導入
- REST LEVEL3 – HATEOASの概念の導入
本書は、現在多くのWeb APIで採用されている「REST LEVEL 2」に対応しており、「REST LEVEL 3」において導入されるHATEOASは導入していません。
HATEOASに関しては、本書の執筆時には「時期尚早」であったと思われますが、HALというHATEOASのための仕様と、その実装のためのライブラリも整備されてきているので、2017年現在は「採用を検討する」くらいのフェーズにはなっていると思います。
まとめ
これからREST APIを開発する人にはとても参考になる書籍だと思います。
gRPCのようにRESTの代替となる技術も出てきているので、RESTさえ知っていればOK、という状況ではなくなってきていますが、今でも主流はRESTでしょう。
ということでオススメです。