Web APIのデザパタ本——「APIデザイン・パターン」
Description
本書は、そのタイトルが示すようにWeb API（application programming interface -- プログラム同士がやり取りするための規則）のデザインパターン（典型的な問題に対する解法）についての本だ。
本書で提示されるデザインパターンは、Googleのエンジニアである筆者の長年の経験が元となっている。それは後にGoogleのルールとして採用され、最終的にAPI Improvement Proposalsとして公開されているとのことなので折り紙付きだ。
リソースの命名規約のような基礎的なものから、GETやPATCHに対するフィールドマスク、標準メソッドで扱うべきでない場合に定義すべきカスタムメソッド、処理時間が長い操作の非同期化、大量データのフィルターやページネーション等といった実用的なものまで網羅されている。
過去に悩んだことのある、リソース内の別のリソースはインラインで展開すべきなのか、それとも参照だけ含めるべきなのかという疑問や、バージョン管理の方針に関する疑問についても方針が示されていて大変勉強になった。
個人的には、一覧取得のAPIでデータのソーティングやデータの総件数をサポートするのはやめておけ、という提案が面白かった。アンチパターンと思ったことはなく実装したことすらあったけれど、Googleが扱っているような世界規模のシステムを考えた場合にはそもそも非現実的というのは納得。
Conclusion
APIは、その定義から開発者が変更を行うと利用者に影響を与えてしまう。そのため、一度公開したら変更することは容易ではなく、最終的に正しければよいという開発スタイルではダメで、最初から正しくなるように開発しなければならない。
動くものを作るのは簡単だが、よくできたものを作るのはとても難しいという点で、APIはプログラムとよく似ている。最初から正しく作るためには、本書のような体系的な知識があるとよいかもしれない。
Web APIを設計／実装する機会のある人にお勧めしたい一冊だけど、気になる点もいくつかある。
通読した人は同意してくれると思うんだけど、説明が本当にくどい。それだけならまだしも、レトリックが多用されてるので疲れる。APIに対してシンプルさを力説してたのに、この本そのものはどうしちゃったんですか？
原著とは関係ないけど誤植が多いのも気になった。あまりの多さにびっくりして、正誤表みてみたけど、全然あんな量じゃなかったぞ。
主にスケールの違いのせいで、Google にとっては理にかなっていても、一般的には過剰かなと思われるデザインパターンもいくつかあることにも注意されたい。
あぁ、それともう一つ。本書の内容は基本的にREST APIが主題になっていて、後発のGraphQLはあまり考慮されてないように見受けられる。GraphQLに明るくないので恐縮だが、私の理解ではGraphQLを採用する場合は、これらのデザインパターンのうちのいくつかはまったく不要になりそうだ。