基本情報

タイトル	API デザイン・パターン
著作者名	JJ Geewax
翻訳者名	松田晃一
書籍	4,785 円
電子版	4,785 円
B5 変	528 ページ
ISBN	978-4-8399-7939-3
発売日	2022 年 08 月 26 日

著者の GitHub を見てみると、バックボーンを伺い知ることが出来ます。 Google Clould の開発者の中の1人ですので、お世話になっている人は多いのではないでしょうか？

github.com

構成

本書は、以下のパートに分かれています。

PART 1 はじめに
PART 2 設計の原則
PART 3 基礎編
PART 4 リソース間の関係
PART 5 コレクションの操作
PART 6 安心と安全

PART 1~2 は、以降の頁を読み進めるための基礎的事項がおさえられ、読者とのベースラインを合わせるためにある部分です。

PART 3~6 は、それぞれのパートで、いくつかの章立てに分かれて基本的な API の設計を手始めに「実際に遭遇しうるような」シチュエーションに対応した設計パターンがまとめられています。

Web API の特殊性/特徴

広義の API は、コンピューターシステムとのやり取りする方法を定義するものと紹介されています。
その中でも「ネットワーク上に公開」され様々な人がリモートで使用することを目的とした特殊な API が「Web API」です。

また、各種 API の中でもWeb API は、「API の開発者」は様々な変更が行えますが、「API の利用者」はコントロールできることが少ないものです。これは、ライブラリをダウンロードして入手し、(やるかどうかはさておき)任意の改修ができてしまういわゆる API ライブラリとは大きく異なっています。

こういった Web API の特殊性から、開発者により行われた変更の影響範囲は非常に大きいものになります。このような責任を伴うような面とともに、「機能」だけを公開しライブラリ本体の知的財産を公開せずに済み、負荷の高い処理を要求する API にはその処理負荷に耐えうるインフラを与え外部から呼び出し、実行環境を利用者の環境/端末から解放できます。

上記のような Web API の構築には、「時間の節約」と「将来の頭痛の種」を取り除くデザインパターンの適用を本書では推奨しています。

それは、「よく設計されたソフトウェアを作る技術のいくつかを API の設計に適用してもうまくいかないことがよくあるからなのです」と本書では語られています。
例えば、反復的なアプローチを取るアジャイル開発プロセスは、このうまくいかないものとして取り上げられています。先に、「API の利用者はコントロールできることが少ない」と述べていました。 Web ページの改修は、その利用者が人であるために変更に対して耐性を持っていますが、API の利用者は開発者でなければ API を利用したユーザーでも無く、API を実行するコンピューターシステムそのものです。人は、画面上のボタンの位置やボタンの種類が変わっても柔軟に対応出来ますが、コンピューターシステムはそう柔軟ではないのです。
API に変更があれば API を利用するシステムにも変更が必要であり、一度決めた設計を大きく違う方向に振り向けることは難しいので、将来を見据えた設計をするための青写真としてよく練られたデザインパターンを適用する価値があるとされています。

Web API のデザイン・パターン

CRUD を構成する標準メソッドに始まり、4つのパート計25章に及んで様々なケースが紹介されています。
中でも「ロングランオペレーション」や「再実行可能ジョブ」「バッチ操作」といった単純な 1 リクエストと対応する 1 応答で完結出来ない処理については、私自身形式化できていない上にそのケースに出会ったときにその時最良の方法を考えるような、揉まれていない設計になっていたように思います。次、このようなケースに遭遇した場合には積極的に採用したい内容でした。
実務で API の設計に取り組まれて来た方にも、これまでの設計の振り返りをするきっかけになるかもしれません。(ただし、先の通りAPIの変更に対して利用側の耐性は高くないので、既に稼働しているものの改善に活かす目的にはおすすめできません。次に生かす。という視点になると思います。)

それぞれの紹介や考え方の解説も詳細であるとともに、それぞれの項目に必ず「トレードオフ」という項目が用意されています。
パターンの適用により何を捨て何を得たのか、パターンとしての欠点をどのように持つのかまで紹介されており、APIを設計する読者の助けになるように思います。

本書での気づき

本書で語られる、各デザインパターンは自身の業務にどのように適用できるのか？という観点で魅力的なものばかりです。

また、それらの導入の足がかりとなる基礎編も興味深いものばかりです。

「第 6 章リソース識別子」では、「リソース識別子とは？」「何が良い識別子にするのか」「良い識別子とは？」のように、掘り下げ 17P も費やされる内容になっています。中でも UUID の頁は、「識別子にはだいたい UUID を選定してしまうなぁ」という場合には、一読の価値があるように思います。「『なぜ識別子には UUID を使う』だけで終わりにしないのか」という理由が書かれており、私も「確かに」と思った内容でした。

感想

全体に発見(と過去を振り返っての後悔)が多い書籍であったように思います。 APIの設計を、仕様変更及び拡張に伴いその時考えられるベストな設計を都度考えているような状況があれば、一定の指針を得られるのではないでしょうか。

私は全編一通り目を通しましたが、本書のWEBページでも「Web API設計のベストプラクティス集」と銘打たれている通り、デザインパターンのカタログと割り切って、ケースとパターンの関連付けを頭の片隅に置くような読み方しておき、実際にパターンの適用の際に改めて必要箇所を読み直すような形が適切であるものと感じます。また、全編覚えておけるほど薄くないページ数(528ページ)を持つ本でもあります。

興味を持たれましたら、一度手に取ってみることをおオススメします。