API デザイン・パターン

本書 "API デザイン・パターン (API Design Patterns)" は、Web API を構築するための一連の設計原則、安全かつ柔軟で再利用可能なパターンを提供するために書かれました。Google Cloud Platform とその API 設計に取り組む著者が、

・API の一貫性、拡張性、可用性を確保する方法について
・安全かつ柔軟で再利用可能な API パターン
・一般的な API の設計を改善する手法

について解説します。コード例は TypeScript で解説。詳細なシナリオ・図解により、API 設計についての理解が深まります。

提供する API が他の開発者から信頼され、便利に使ってもらえるようにするためのベストプラクティスを提供します。

［本書まえがきより］
ソフトウェアが「うまく設計されている」とはどういうことなのか、「よく設計された Web API」とは何か。
私は自分自身で答えを出そうとし、実際に使ってみた情報などを何年もかけ集約し、Luke Sneeringer と私で Google のルールとして明文化し、それは最終的に AIP.dev (google.aip.dev) という形で提供することになりました。これらのルールはある種の法律のようなもので「何をすべきか」は書かれていても、「なぜそうすべきか」は書かれていません。この本で私が目指したのは実践的なガイドラインと、その理由を論理的に説明することです。この本で取り上げたトピックが、API デザインという魅力的かつ複雑な世界において、多くの会話や将来の仕事のきっかけとなることを願っています。

［対象読者］Web API を構築している人、構築する予定の人。API を一般に公開することを検討している場合に本書は有用です。JSON などのシリアライゼーション・フォーマットや一般的なストレージ知識、HTTP とそのメソッド (GET や POST) に精通していることは本書を理解する助けとなります。
目次:
PART 1 はじめに
第 1 章 API 入門
第 2 章 API デザインパターン入門

PART 2 設計の原則
第 3 章 名前付け
第 4 章 リソースの範囲と階層
第 5 章 データ型とデフォルト値

PART 3 基礎編
第 6 章 リソース識別子
第 7 章 標準メソッド
第 8 章 部分的な更新と取り出し
第 9 章 カスタムメソッド
第 10 章 ロングランオペレーション
第 11 章 再実行可能ジョブ

PART 4 リソース間の関係
第 12 章 シングルトンサブリソース
第 13 章 相互参照
第 14 章 アソシエーションリソース
第 15 章 カスタムメソッド: add、remove
第 16 章 ポリモーフィズム

PART 5 コレクションの操作
第 17 章 コピーと移動
第 18 章 バッチ操作
第 19 章 条件に基づく削除
第 20 章 匿名書き込み
第 21 章 ページ分割
第 22 章 フィルタリング
第 23 章 インポートとエクスポート

PART 6 安心と安全
第 24 章 バージョンと互換性
第 25 章 論理削除
第 26 章 リクエストの重複実行回避
第 27 章 リクエストの検証
第 28 章 リソースリビジョン
第 29 章 リクエストの再試行
第 30 章 リクエストの認証

公開した Web API を、利用者を困らせずに長く育てていくための設計判断を、名前付けから認証まで 30 の章に分けて示した設計書です。『API デザイン・パターン』 (JJ Geewax 著、松田 晃一 訳、マイナビ出版、2022 年 8 月 26 日発売) は、原書 API Design Patterns の日本語版で、Web API 設計のベストプラクティス集とうたわれています。著者は Google のソフトウェアエンジニアで、Google で始まった API 設計標準をめぐる業界横断の取り組み AIP.dev の共同設立者と紹介されており、コード例は TypeScript で書かれています。

名前付けから認証まで、6 部 30 章の構成

本書は 6 つの PART に分かれています。PART 1「はじめに」で API とデザインパターンの考え方を導入し、PART 2「設計の原則」では名前付け、リソースの範囲と階層、データ型とデフォルト値という土台を扱います。PART 3「基礎編」はリソース識別子、標準メソッド、部分的な更新と取り出し、カスタムメソッド、ロングランオペレーション、再実行可能ジョブ、PART 4「リソース間の関係」はシングルトンサブリソースや相互参照、アソシエーションリソース、ポリモーフィズムを取り上げます。PART 5「コレクションの操作」はコピーと移動、バッチ操作、条件に基づく削除、匿名書き込み、ページ分割、フィルタリング、インポートとエクスポートを、PART 6「安心と安全」はバージョンと互換性、論理削除、リクエストの重複実行回避、リクエストの検証、リソースリビジョン、リクエストの再試行、リクエストの認証を扱います。

ルールの「なぜ」を説明する設計書という位置づけ

API の設計が難しいのは、いったん公開すると利用者のコードがその形に依存し、後から自由に直せなくなるからです。フィールド名ひとつ、エラーの返し方ひとつが、利用者の数だけ固定されていきます。だからこそ、多くの API を抱える組織は命名や操作の形をそろえる規約を持ちますが、規約は何をすべきかを定めても、なぜそうすべきかまでは語らないことが少なくありません。版元が紹介するまえがきで著者は、Google のルールとして明文化した AIP.dev について、まさにこの点を挙げ、実践的なガイドラインとその理由を論理的に説明することを本書の目的にしたと述べています。たとえば一覧の取得を カーソル方式のページ分割 にするか、ネットワークの失敗で再送されたリクエストを べき等キー で見分けるか、API のバージョン管理 で後方互換をどこまで守るかといった判断は、正解を暗記するより、背後にある利用者側の困りごとを理解しておくほうが応用が利きます。規約の背景を知りたい人にとって、本書はその説明を章単位で引ける資料になります。

HTTP と JSON を前提に読む、向く読者と向かない目的

版元は対象読者を、Web API を構築している人と構築する予定の人とし、とくに API を一般に公開することを検討している場合に有用だと案内しています。JSON などのシリアライゼーション・フォーマット、一般的なストレージの知識、HTTP とそのメソッド (GET や POST) に通じていることが理解の助けになるとされているため、HTTP の基本から学びたい段階なら、先に Web API の入門書を通しておくほうが進めやすいでしょう。また章題はどれも設計上の論点で、特定のフレームワークでサーバーを組み立てる手順を学ぶ本ではありません。実装の書き方を急いで知りたい場合は目的が合いにくい一方、設計レビューで「なぜこの形にするのか」を言葉で説明したい人には、そのまま使える論拠が手に入ります。

社外や他チームに公開する API の設計を任された人、複数の API の命名や操作の形をそろえる規約づくりに関わる人にとって、設計の論点を章ごとに参照できる本書は、手元に置いて設計の迷いを減らすための一冊です。まず PART 2 の設計の原則を読み、あとは目の前の課題に近い章から開いていく読み方が合います。