すぐに役に立つものはすぐに陳腐化してしまうから方法ではなく設計の本を読む - API Design Patterns の読書感想文

あなたがさっきまで読んでいた技術的に役立つ記事は、10年後も使えるでしょうか。~~ほとんどの場合でいいえ~~

この問いに真正面から殴られたのは数か月前、リリース前夜の「とりあえずこれで走らせよう」が翌朝に別サービスを巻き込む事故になったときでした。Slackで「なんで昨日の変更でメトリクスが暴れてるのか」と聞かれ、胃がキリキリしたまま休日をつぶす羽目に。目先のテクニックだけで乗り切った仕事は、想像より早く自分を噛みに来る。だから設計そのものの筋肉を付けたい、という切実さを忘れないうちに本を開きました。

ただし、先に言っておきます。Design Patternsは設計そのものではありません。 パターンを知っているだけで良い設計ができるわけではない。10年前の「RESTが正義」という原則は、GraphQLやgRPCによって相対化されました。原則も陳腐化します。それでも原則を学ぶ価値があるとすれば、「不変の正解を知る」ことではなく、「なぜその原則が生まれ、なぜ相対化されたのかの構造を理解する」ことにあります。この前提を共有した上で、読み進めてください。

はじめに

日曜の昼過ぎだった。コーヒーを淹れて、ソファに座った。テレビはつけていない。スマートフォンも机に置いたまま。ただ、窓の外を見ていた。

休んでいる、と言えば休んでいるのだろう。体を動かしていないし、仕事もしていない。でも、休んだ気がしない。金曜の深夜に起こした障害のことが、ずっと頭の隅にある。リリース前に「とりあえずこれで」と書いたコードが、翌朝には別のサービスを巻き込んで止まっていた。Slackの通知音が鳴り続けるのを、布団の中で聞いていた。

あのとき何が足りなかったのか、と考える。技術力だろうか。たぶん違う。新しいフレームワークを知らなかったからでもない。もっと手前の、地味なところだった気がする。「なぜこう作るのか」という問いを、私は持っていなかった。動けばいい。間に合えばいい。そう思っていた。思っていたが、それが正しかったのかは分からない。

480ページある。「API Design Patterns」という本の話だ。手に取ったのは、障害対応が終わった翌週のことだった。

learning.oreilly.com

API Design Patterns (English Edition)

作者:Geewax, JJ
Manning

Amazon

正直に言うと、この本を読んだからといって、次から失敗しなくなるとは思っていない。たぶんまた同じようなことをやる。それでも、何かが変わるかもしれないと思った。思いたかった、という方が正確かもしれない。

著者はAPIを「コンピュータシステム間の相互作用を定義する特別な種類のインターフェース」と書いている。私が漠然と感じていた「APIは契約だ」という感覚を、この一文が言葉にしてくれた気がした。気がしただけで、本当にそうなのかは分からない。

netmarkjpさんの「現場がさき、プラクティスがあと、原則はだいじに」という資料も、同じ頃に読み返した。原則を大事にしながら現場をやっていく。言葉にすると簡単だが、実際にやるのは難しい。難しいが、やるしかない。

地下鉄の揺れに耐えながらKindle英語版を読んでいた頃は、何度も同じページに戻っていた。日本語版が届いてからは、章ごとの言い回しがすっと入ってきた。母語で読み直すと、刺さり方が変わる。その感覚を、久しぶりに味わった。

APIデザイン・パターン (Compass Booksシリーズ)

作者:JJ Geewax
マイナビ出版

Amazon

読み終えて、最初にやったのは過去の自分のPull Requestを開くことだった。「ここは将来困りそう」というコメントが残っていた。いや、もう困っている。困っているのに、当時の自分はそれが分からなかった。

この本を読んだから、明日から設計がうまくなるわけではない。原則を知っていても、現場で使えなければ意味がない。それは分かっている。分かっているが、何も持たないよりはマシだと思う。思うことにしている。

www.oreilly.co.jp

この記事の執筆にはLLMを使っている。深夜に箇条書きを投げ込んで、翌朝に整える。そういう流れで書いた。ときどきLLMっぽい言い回しが残っているかもしれない。ただ、障害対応で冷や汗をかいた記憶や、設計で迷った感覚は、私のものだ。それだけは確かだと思う。

Xで時折紹介する本の中には、わずか1行で要点を伝えられるものもある。けれど、その本が私に与える価値は長さだけでは測れない。紹介が短いから劣っているわけでも、長いから優れているわけでもない。読者にどれだけ影響を与え、どれほど思考を喚起するかが本質だ。

はじめに
目次
Part 1 Introduction
Part 2 Design principles
Part 3 Fundamentals
Part 4 Resource relationships
Part 5 Collective operations
Part 6 Safety and security
おわりに

原理・原則と方法論は相互に補完し合う関係にあります。原則が長期的に通用する基盤を提供し、方法論がそれを実践に落とし込む。言いたいことは言ったので本編どうぞ。

Part 1 Introduction

このパートでは、APIの基本概念、重要性、「良い」APIの特性を順番に説明しています。APIは「コンピュータシステム間の相互作用を定義する特別な種類のインターフェース」と定義され、その意義が強調されています。Web APIの特性やRPC指向とリソース指向の比較に触れたあと、運用可能性・表現力・シンプル性・予測可能性といった観点を掘り下げています。

1 Introduction to APIs

「API Design Patterns」の第1章「Introduction to APIs」は、APIの基本概念から始まり、その重要性や設計哲学を丁寧に整理しています。章の後半では「良い」APIの特性まで一気に踏み込みます。著者はGoogle Cloud Platformのエンジニアとして長年APIの設計と実装に携わってきた経験を持ち、机上の空論ではなく現場で擦り切れたノウハウをまとめてくれています。

この章で特に突き刺さったのは以下の3点です。

APIは単なるI/Oではなく、チーム間・組織間の契約そのものだという視点
「良い」APIの特性を、運用・表現・シンプルさ・予測可能性で分解して語れる言語
失敗例と成功例を行き来しながら、改善の手触りを具体的に示している構成

まず、APIの定義から始めましょう。著者は、APIを「コンピュータシステム間の相互作用を定義する特別な種類のインターフェース」と説明しています。この一見シンプルな定義の背後には、Google Cloud Platform上の数多くのAPIを設計・実装してきた著者の深い洞察が隠れています。例えば、Google Cloud StorageやBigQueryなどのサービスのAPIは、この定義を体現しており、複雑なクラウドリソースへのアクセスを簡潔なインターフェースで提供しています。

この定義は、現場の感覚とも一致しています。私たちの日常業務の多くは、APIの設計・実装・維持に費やされているからです。「APIに遊ばれるだけの日々」という表現は、多くのエンジニアの共感を呼ぶでしょう。しかし著者の視点は、APIを単なる技術要素ではなく、システム設計の中核を成す概念として捉え直すきっかけを与えてくれます。

私自身、初めて本番APIを任されたときは「とにかく動けばいい」と念じながらRESTっぽいエンドポイントを量産しました。結果、半年後に別チームのgRPCサービスとつなぐ際、命名のバラバラさと表現力の貧弱さで完全に詰み、深夜の会議で謝り倒す羽目に。あの時「相互作用のインターフェース」という感覚を持っていたら、もう少しマシな折り合いを付けられたのにと今でも痛感します。

Googleが提供しているAPI設計ガイドも、非常に優れたAPIの例を紹介しています。このガイドは、著者が所属している Google のエンジニアたちが長年の経験から得た知見をまとめたものであり、「API Design Patterns」の内容を補完する貴重なリソースとなっています。

cloud.google.com

このガイドと本書を併せて読むことで、APIの設計に関するより包括的な理解が得られます。例えば、ガイドで推奨されている命名規則やエラー処理の方法は、本書で説明されている「良い」APIの特性と密接に関連しています。

この章は、APIの基本を学ぶ初心者から、より良いAPI設計を模索する経験豊富な開発者まで、幅広い読者に価値を提供します。著者の洞察は、私たちがAPIをより深く理解し、より効果的に設計・実装するための道標となるでしょう。

Web APIの特性と重要性

特に印象的だったのは、著者がWeb APIの重要性と特性を強調していることです。Web APIはネットワーク越しに機能を公開しつつ、内部の仕組みや計算資源を意識させません。マイクロサービスやクラウドアプリケーションでは、この「舞台裏を見せない」性質が生命線になります。著者はそのエッセンスを、以下のような観点に分解して説明していました。

提供者は制御権を持つが、利用者の制御権は極端に小さい
エンドポイントの一貫性と表現力が、組織全体の開発速度を左右する
バージョン管理と漸進的なリリースこそが、破壊的変更を和らげる唯一の道具

例えば、マイクロサービスは、その内部の仕組みの詳細を隠しつつ、明確に定義された使い方（API）を通じて他のサービスとやり取りします。これにより、サービス同士の依存関係を少なく保ちながら、システム全体の柔軟性と拡張性を高めることができます。

著者は、Web APIの特徴として、API提供者が大きな制御力を持つ一方で、利用者の制御力は限られていることを指摘しています。これは実務において重要な考慮点です。例えば、APIの変更が利用者に与える影響を慎重に管理する必要があります。APIのバージョン管理や段階的な導入などの技術を適切に活用することで、APIの進化と利用者のシステムの安定性のバランスを取ることが求められます。提供者がどれだけ慎重でも影響は必ず出るので、「影響が出る前提で、どこまで柔らかく着地させられるか」を考える癖を付けておきたいところです。

実際、私はAPI側の事情だけを優先してエンドポイントを変更し、リリース直後に顧客のSDKが一斉に壊れる事故を経験しました。提供者側が「たいした変更じゃない」と思っていても、利用者の選択肢はほとんどなく、怒りの問い合わせが山のように届きます。制御力の非対称性を肌感覚で理解してからは、軽い気持ちでBreaking changeを出すことがなくなりました。

API設計アプローチの比較

著者は、APIの設計アプローチとして、RPC (Remote Procedure Call) 指向とリソース指向の2つを比較しています。この比較は非常に興味深く、実際の開発現場での議論を想起させます。例えば、gRPCはRPC指向のAPIを提供し、高性能な通信を実現します。一方で、REST APIはリソース指向のアプローチを取り、HTTPプロトコルの特性を活かした設計が可能です。

著者が提唱するリソース指向APIの利点、特に標準化された操作（CRUD操作）とリソースの組み合わせによる学習曲線の緩和は、実際の開発現場でも感じる点です。例えば、新しいマイクロサービスをチームに導入する際、リソース指向のAPIであれば、開発者は既存の知識（標準的なHTTPメソッドの使い方など）を活かしつつ、新しいリソースの概念を学ぶだけで素早く適応できます。

数年前、社内で「次の大規模連携基盤をgRPC一本で行くか、RESTで刻むか」をめぐって毎晩議論したことがあります。私は「既存チームが慣れているRESTから始めよう」と主張したのですが、理由を感覚でしか語れず押し切られかけました。この章を読んでからは、「学習コスト」「リソースの予測可能性」という言語で説明できるようになり、ようやく議論のテーブルに乗れた感覚があります。

「良い」APIの特性

「良い」APIの特性に関する著者の見解は、特に重要です。著者は、良いAPIの特性として以下の4点を挙げています。

運用可能性（Operational）
表現力（Expressive）
シンプル性（Simple）
予測可能性（Predictable）

これらの特性は、現代のソフトウェア開発において重要です。

運用可能性とSREの視点

運用可能性に関しては、APIが機能的に正しいだけでなく、パフォーマンス、スケーラビリティ、信頼性などの非機能要件を満たすことが、実際の運用環境では重要です。例えば、並行処理機能を活用して高性能なAPIを実装し、OpenTelemetryやPrometheusなどのモニタリングツールと連携してメトリクスを収集することで、運用可能性の高いAPIを実現できます。

syu-m-5151.hatenablog.com

表現力と使いやすさ

表現力に関する著者の議論は、API設計の核心を突いています。APIは単に機能を提供するだけでなく、その機能を明確かつ直感的に表現する必要があります。例えば、言語検出機能を提供する場合、TranslateTextメソッドで間接的に言語を推測するよりも、DetectLanguageという専用メソッドを用意する方が、使用者の思考コストを一気に下げられます。

マイクロサービス間の統合で何度も痛感しましたが、「名前で迷わせない」「必要なパラメータが一目で分かる」だけでレビュー時間が大幅に短縮されます。著者の主張を踏まえ、最近はAPI仕様を書き始める前に以下のチェックリストで自問しています。

エンドポイント名だけで役割を言い当てられるか
入出力のフィールドは、呼び出し側の自然な語彙になっているか
暗黙の前提条件をドキュメント外に追い出していないか

マイクロサービスアーキテクチャ第2版

作者:Sam Newman
オーム社

Amazon

シンプル性と柔軟性のバランス

著者が提案する「共通のケースを素晴らしく、高度なケースを可能にする」というアプローチは、実際のAPI設計で常に意識すべき点です。例えば、翻訳APIの設計において、単純な言語間翻訳と、特定の機械学習モデルを指定した高度な翻訳の両方をサポートする方法が示されています。

以前、A/BテストプラットフォームのAPIを作った際に「高度な条件指定」を前面に出して失敗しました。ほとんどのユーザーはシンプルなAB実験しか求めていなかったのに、複雑な設定を強要し、サポート工数が爆発。今なら著者の言葉どおり、まずは共通ケースを気持ちよく成功させ、必要になった瞬間に高度なフラグを追加すれば良かったと分かります。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

Amazon

予測可能性とコード一貫性

予測可能性に関する著者の主張は、特に共感できる点です。APIの一貫性、特にフィールド名やメソッド名の命名規則の統一は、開発者の生産性に直結します。多くのチームではコードスタイルのガイドラインを用意していますが、APIレイヤーでも同じくらい厳しく扱うべきです。

予測可能なAPIは、学習コストと誤用のリスクを下げます。私は過去に、同じ機能を提供する2つのエンドポイントでリクエスト形式が微妙に違い、SDK側のバグを長期間放置してしまったことがあります。今は以下のようなルールを明文化し、レビュー時に必ずチェックするようにしました。

フィールド順序や命名規則を、既存APIと照らし合わせる
レスポンス構造をテンプレート化し、例外を極力作らない
変更時は互換性マトリクスを添えて、利用者が迷うポイントを先回りで説明する

著者の主張に対する補完的視点

しかし、著者の主張に対して、いくつかの疑問や補完的な視点も考えられます。例えば、リソース指向APIが常に最適解であるかどうかは、議論の余地があります。特に、リアルタイム性が求められる場合や、複雑なビジネスロジックを扱う場合など、RPC指向のアプローチが適している場合もあります。gRPCを使用したストリーミングAPIなど、リソース指向とRPC指向のハイブリッドなアプローチも有効な選択肢となりうるでしょう。

また、著者はAPI設計の技術的側面に焦点を当てていますが、組織的な側面についても言及があればより立体的になったでしょう。例えば、マイクロサービスアーキテクチャにおいて、異なるチームが管理する複数のサービス間でAPIの一貫性を保つためには、技術的な設計パターンだけでなく、組織的なガバナンスや設計レビューのプロセスも重要です。

APIのバージョニングや後方互換性の維持に関する詳細な議論があれば、より実践的な内容になったかもしれません。これらの点は、システムの安定性と進化のバランスを取る上で重要です。

総括と実践への応用

総括すると、この章はAPIの基本概念と設計原則に関する優れた導入を提供しています。著者の主張は、日々の実践に直接適用できる洞察に満ちています。

特に、「良い」APIの特性はAPI設計の指針として有用です。これらの原則を意識しながら設計することで、使いやすく、拡張性があり、運用しやすいAPIを実現できます。私は週次のAPIレビューで、以下の3点を定例観点として組み入れました。

運用チームがSLOを定義できるだけのメトリクスとログがあるか
エンドポイントの命名やレスポンス構造が既存資産と整合しているか
共通ユースケースが迷わず成功し、上級者が工夫できる余白があるか

また、リソース指向APIの利点に関する著者の主張は、RESTful APIの設計において特に参考になります。多くのWebフレームワークを使用してRESTful APIを実装する際も、著者が提唱するリソース指向の原則を意識すれば、一貫性のある設計が可能になります。

ただし、現場では原則を機械的に適用するだけでは不足します。具体的なユースケースや非機能要件を踏まえ、トレードオフを判断する必要があります。例えば、リアルタイム通信が必須ならRESTよりgRPCを選ぶ、あるいはメッセージングを併用して表現力を補うなど、状況に応じた柔軟さが求められます。API設計のプロセスには、技術チームだけでなく、プロダクトマネージャーやUX担当者など、多様なステークホルダーを巻き込むことも不可欠です。

継続的改善と進化の重要性

APIの設計は一度で完成するものではない。継続的に磨き込むプロセスだ。分かっている。分かっているが、リリース直前になると忘れる。だから私は章末で紹介されている観点を、以下の「改善サイクルメモ」に落とし込んで、毎週のレビューで強制的に目に入るようにしている。

主要エンドポイントのレイテンシとエラーレートを毎週モニタリングし、兆候をSlackに共有する
サポート窓口に届いたクライアント視点の苦情を、API仕様へのフィードバックチケットにして公開する
四半期ごとにAPIスタイルガイドを見直し、破壊的変更への「警報レベル」を可視化する

この章で学んだ原則を、単なる理論ではなく実際の開発プラクティスに統合するには、チェックリスト化と公開が欠かせません。既存のAPIを予測可能性やシンプル性の観点で棚卸しするだけでも、改善余地が見つかります。

結論

この章はAPIデザインの基本原則を理解し、実践するための出発点だ。原則を知っているだけでは意味がない。日々のプラクティスに組み込んで初めて効果が出る。私は読了後、過去のPRを開いて「運用可能性」「予測可能性」の観点でセルフレビューをした。恥ずかしい箇所がいくつも見つかった。見つかったということは、少なくとも視点は身についたのだと思う。思いたい。

2 Introduction to API design patterns

「API Design Patterns」の第2章「Introduction to API design patterns」は、API設計パターンの基本概念から始まり、その重要性、構造、そして実際の適用に至るまでを一気に横断します。私はこの章を読んだ直後、社内の設計ミーティングで「なぜ今パターンが必要なのか」を説明するために、章の骨子をA4一枚にまとめて配りました。パターンを知らないメンバーにもイメージを伝えやすかったのを覚えています。

API設計パターンの定義と重要性

API設計パターンは、ソフトウェア設計パターンの一種であり、APIの設計と構造化に関する再利用可能な解決策を提供します。著者は、これらのパターンを「適応可能な設計図」と巧みに表現しています。この比喩は、API設計パターンの本質を非常によく捉えています。建築の設計図が建物の構造を定義するように、API設計パターンはAPIの構造とインターフェースを定義します。しかし、重要な違いは、API設計パターンが固定的ではなく、様々な状況に適応可能であるという点です。

著者は、API設計パターンの重要性をAPIの硬直性という観点から説明しています。APIは一度公開されると、消費者が既存のインターフェースに依存するため、変更が困難になります。私は過去に、初期設計を勢いで決めた結果、1年後に互換性維持で身動きが取れなくなりました。新機能を入れるたびにSDKの破壊的変更を伴い、サポート窓口がパンク。あの時、せめて識別子の扱いやバージョニングのパターンを先に押さえておけばと何度も悔やみました。

この硬直性は、システムの運用性と信頼性にも直結します。著者が強調する通り、設計パターンを初期段階から採用することは、将来の変更や拡張を容易にし、長期的な保守性を高める最善策です。私は章の内容を自分なりに噛み砕き、「公開前チェックリスト」に以下の項目を追加しました。

エンドポイント追加時に再利用できる共通構造を定義したか
バージョニング、廃止告知、互換性維持の方針をドキュメント化したか
利用者が影響を受ける変更を、SDKやCLIなど別チャネルでも告知できる体制を整えたか

API設計パターンの構造

著者は、API設計パターンの構造を詳細に説明しています。特に興味深いのは、パターンの記述に含まれる要素です。

名前とシノプシス
動機
概要
実装
トレードオフ

この構造は、パターンを理解し適用する上で有用です。特に、トレードオフの項目は重要です。ソフトウェア工学において、すべての決定にはトレードオフが伴います。パターンを適用する際も例外ではありません。脱線しますがアーキテクチャのトレードオフについてはこちらがオススメです。

ソフトウェアアーキテクチャの基礎 ―エンジニアリングに基づく体系的アプローチ

Amazon

トレードオフの理解はリスク管理と密接に関連しています。例えば、あるパターンを採用することで、システムの柔軟性が向上する一方で、複雑性も増加するかもしれません。このトレードオフを理解し、適切に管理することは、システムの信頼性とパフォーマンスを最適化する上で重要です。

実践的な適用：Twapiの事例研究

著者は、Twitter風のAPIであるTwapiを爆誕させて例に取り、API設計パターンの実践的な適用を示しています。この事例研究は、理論を実践に移す上で有用です。

特に興味深いのは、メッセージのリスト化とエクスポートの2つに絞って議論している点です。どちらも「最初は簡単そうに見えて、実際はチューニング地獄になる」典型例で、私たちが日常的に向き合う課題でもあります。

メッセージのリスト化

著者は、まずパターンを適用せずにメッセージをリスト化する機能を実装し、その後にページネーションパターンを適用した実装を示しています。このコントラストは非常に教育的です。

パターンを適用しない初期の実装は、以下のようになっています。

interface ListMessagesResponse {
  results: Message[];
}

この実装は一見シンプルですが、著者が指摘するように、データ量が増えると破綻します。数十万件のメッセージを一度に返そうとすると、レスポンスサイズは巨大化し、帯域は圧迫され、クライアントも処理しきれません。数年前の私はこの罠に見事にハマり、クエリのタイムアウトを量産しました。

これに対し、ページネーションパターンを適用した実装は以下のようになります。

interface ListMessagesRequest {
  parent: string;
  pageToken: string;
  maxPageSize?: number;
}

interface ListMessagesResponse {
  results: Message[];
  nextPageToken: string;
}

この実装では、クライアントはpageTokenとmaxPageSizeを指定し、必要な量を段階的に取得します。大量のデータを効率的に扱えるだけでなく、サーバー負荷の平準化にもつながります。私はこれを読んだ翌日に、自社APIのListFooエンドポイントへ適用しました。導入時に意識したのは以下の3点です。

既存レスポンスとの互換性を保つため、pageToken導入前後のリリースを2段階に分ける
監視ダッシュボードでページサイズ別のヒストグラムを可視化し、異常を素早く検知する
ドキュメントに「最初は32件から試す」といった推奨値を明記し、クライアント実装を迷わせない

データのエクスポート

データのエクスポート機能に関しても、著者は同様のアプローチを取っています。まずパターンを適用しない実装を示し、その後にImport/Exportパターンを適用した実装を提示しています。

パターンを適用しない初期の実装は以下のようになっています。

interface ExportMessagesResponse {
  exportDownloadUri: string;
}

この実装は、エクスポートされたデータのダウンロードURLを返すだけの単純なものです。しかし、著者が指摘するように、この方法には幾つかの制限があります。例えば、エクスポート処理の進捗状況を確認できない、エクスポート先を柔軟に指定できない、データの圧縮や暗号化オプションを指定できないなどの問題があります。

これに対し、Import/Exportパターンを適用した実装は以下のようになります。

interface ExportMessagesRequest {
  parent: string;
  outputConfig: MessageOutputConfig;
}

interface MessageOutputConfig {
  destination: Destination;
  compressionConfig?: CompressionConfig;
  encryptionConfig?: EncryptionConfig;
}

interface ExportMessagesResponse {
  outputConfig: MessageOutputConfig;
}

この実装では、エクスポート先やデータの処理方法を柔軟に指定できるようになっています。さらに、著者は長時間実行操作パターンを組み合わせることで、エクスポート処理の進捗状況を追跡する方法も提示しています。

このパターンの適用はシステムの運用性と可観測性を大幅に向上させます。エクスポート処理の進捗を追跡できるようになることで、問題が発生した際の迅速な対応が可能になります。また、エクスポート設定の柔軟性が増すことで、様々なユースケースに対応できるようになり、システムの利用可能性が向上します。

API設計パターンの適用：早期採用の重要性

著者は、API設計パターンの早期採用の重要性を強調しています。これは非常に重要な指摘です。APIを後から変更することは困難であり、多くの場合、破壊的な変更を伴います。

例えば、ページネーションパターンを後から導入しようとした場合、既存のクライアントは全てのデータが一度に返ってくることを期待しているため、新しいインターフェースに対応できません。これは、後方互換性の問題を引き起こします。

この問題はシステムの安定性と信頼性に直接影響します。APIの破壊的変更は、依存するシステムやサービスの機能停止を引き起こす可能性があります。これは、サービスレベル目標（SLO）の違反につながる可能性があります。

したがって、API設計パターンの早期採用は、長期的な視点でシステムの安定性と進化可能性を確保するための重要な戦略と言えます。これは、「設計負債」を最小限に抑え、将来の拡張性を確保することにつながります。

結論

本章は、API設計パターンの基本概念と重要性を明確に示しています。特に、APIの硬直性に焦点を当て、設計パターンを早期に採用する理由を具体的に提示している点が印象的でした。後からテコ入れしようとすると、既存クライアントとサービス間の依存が邪魔をして身動きが取れなくなる――この危機感が全編に通底しています。

この章で学んだ内容は、システムの長期的な信頼性・可用性・保守性を確保するうえで非常に役立ちます。API設計パターンを適切に適用すれば、スケーラビリティや運用性、可観測性を底上げできます。とはいえ、パターンの適用には必ずトレードオフが伴います。複雑性の跳ね上がりや実装コストをどこまで許容するか、チームの文脈に合わせて判断しなければなりません。

結局のところ、API設計は単なる技術的課題ではなく、アーキテクチャ、開発プロセス、運用体制を巻き込む総合格闘技だ。パターンを「早めに選ぶ」「継続的に見直す」という姿勢をチームで共有できれば、APIの進化速度と安定性を両立させやすくなる。させやすくなるが、チームに共有しても読まれないことは多い。それでも書く。書いた記録が残る。半年後に「あのとき決めましたよね」と言える。それだけでも価値はある。

Part 2 Design principles

ここでは、APIデザインの核心となる原則が議論されています。命名規則、リソースのスコープと階層、データ型とデフォルト値、リソースの識別子、標準メソッド、部分的な更新と取得、カスタムメソッドなどの重要なトピックが取り上げられています。これらの原則は、一貫性があり、使いやすく、拡張性のあるAPIを設計する上で不可欠です。

3 Naming

「API Design Patterns」の第3章「Naming」は、API設計における命名の重要性、良い名前の特性、言語・文法・構文の選択、コンテキストの影響、データ型と単位の扱い、そして不適切な命名がもたらす結果を幅広く扱います。この章を通じて、著者は命名が単なる表面的な問題ではなく、使いやすさ・保守性・長期的な成功に直結する設計判断だと強調しています。

命名の重要性

著者は、命名がソフトウェア開発において避けられない、そして重要な側面だと強調します。APIではなおさらです。利用者が最初に触れるのはエンドポイント名やフィールド名であり、それが理解できなければドキュメントすら読んでもらえません。私は過去に、Issueリソースを「課題」と「チケット」で表記ゆれさせ、社内外の開発者を混乱させました。半年後に名称を統一しようとしたとき、SDKをすべて書き換える羽目になり、心底反省しました。

ルールズ・オブ・プログラミング ―より良いコードを書くための21のルール

作者:Chris Zimmerman
オーム社

Amazon

マイクロサービスやクラウドネイティブ環境では、命名の揺れがそのまま認知コストになります。Kubernetes上で稼働するサービス群を例にすると、部署ごとにCreate/Add/Registerと動詞がバラつくたびに、依存関係や責務分担を推測する時間が増えます。著者の主張を受け、私は以下のルールをチームの「命名ガードレール」として掲示しました。

リソース名は単数形の英語名詞で統一する（UsersではなくUser）
動詞はCRUDの基本セットに揃え、カスタム動詞はレビューで承認する
時制は現在形固定。「GetUserInfo」ではなく「GetUser」

著者はAPIの名前を変える難しさにも触れます。後方互換性の観点で、一度公開した名前は事実上の契約です。セマンティックバージョニングを採用している場合、名前の変更はメジャーバージョンアップに相当し、すべてのクライアントが影響を受けます。私はこれを痛感し、リリース前レビューに「命名棚卸し」ステップを追加しました。フィールド名・エンドポイント名・エラーコードを一覧化して、重複や紛らわしさがないかを全員でチェックします。10分の投資で、後日の雪崩を防げると考えています。

良い名前の特性

著者は、良い名前の特性として「表現力」「シンプルさ」「予測可能性」の3つを挙げています。私はこれをそのまま命名レビューのチェックリストにしました。

表現力: 名前が表す概念を即座に伝えられているか。レビューでは「これが初見の開発者でも目的を言い当てられるか」を確認します。CreateAccountのように動詞＋対象を明示した名前は、自己文書化につながります。

シンプルさ: 不要な装飾を排し、本質だけを伝えているか。UserSpecifiedPreferencesのように冗長な名前は避け、UserPreferencesで十分な場合は短くします。私は「3語以内」をワーニングラインに設定しました。

予測可能性: 同じ概念に同じ名前を使えているか。API全体で「Create/Update/Delete」を共通動詞にするなど、パターン化が重要です。以下の観点をレビュー時に使っています。

既存リソースの命名と一致しているか（例: FooId vs FooID）
同じ処理なのに異なる動詞を使っていないか
パラメータの単位やデータ型が名前から推測できるか（DurationSecondsなど）

Rustの文脈でもこれらは重要です。Rustの標準ライブラリは動詞＋名詞で短くまとめた関数名が多く、API設計でも同じリズムを保つと開発者の学習コストが下がります。

言語、文法、構文の選択

著者は、API設計における言語・文法・構文の選択も外せない論点だと説きます。私はこれを読んで「命名ガバナンス3点セット」をチームに導入しました。

言語: 仕様テンプレートに「アメリカ英語以外は使用しない」と明文化。多国籍チームでも迷わず英語で統一できるようになりました。
文法: 動詞は命令形を基本にし、CreateBookやDeleteWeatherReadingのように意図を先に示す。RESTのHTTP動詞とも噛み合い、名前だけで行為が伝わります。
構文: ケース（camelCase/snake_case/kebab-case）をリソース種別ごとに固定し、例外は必ずレビューする。Rustではフィールドをsnake_caseで定義し、serdeの#[serde(rename_all = "camelCase")]でJSONのcamelCaseに対応させると開発体験が良くなりました。

use async_trait::async_trait;

#[async_trait]
pub trait UserService {
    async fn create_user(&self, user: &User) -> Result<(), Error>;
    async fn get_user_by_id(&self, id: &str) -> Result<User, Error>;
    async fn update_user_profile(&self, id: &str, profile: &UserProfile) -> Result<(), Error>;
}

このような一貫した命名規則は、API の使用者が新しいエンドポイントや機能を容易に予測し、理解することを可能にします。

コンテキストと命名

著者は、命名におけるコンテキストの重要性を強調しています。同じ名前でも、異なるコンテキストで全く異なる意味を持つ可能性があるという指摘は、特にマイクロサービスアーキテクチャにおいて重要です。

例えば、Userという名前は、認証サービスでは認証情報を持つエンティティを指す可能性がありますが、注文管理サービスでは顧客情報を指す可能性があります。このような場合、コンテキストを明確にするために、AuthUserやCustomerUserのように、より具体的な名前を使用することが望ましいでしょう。

これは、ドメイン駆動設計（DDD）の概念とも密接に関連しています。DDDでは、各ドメイン（またはバウンデッドコンテキスト）内で一貫した用語を使用することが推奨されます。API設計においても、この原則を適用し、各サービスやモジュールのドメインに適した名前を選択することが重要です。

例えば、Eコマースシステムのマイクロサービスアーキテクチャを考えてみましょう：

注文サービス: Order, OrderItem, PlaceOrder
在庫サービス: InventoryItem, StockLevel, ReserveStock
支払サービス: Payment, Transaction, ProcessPayment

各サービスは、そのドメインに特化した用語を使用しています。これにより、各サービスの責任範囲が明確になり、他のサービスとの境界も明確になります。

データ型と単位

著者は、データ型と単位の扱いについても詳細に論じています。特に、単位を名前に含めることの重要性が強調されています。これは、API の明確さと安全性を高める上で重要です。

例えば、サイズを表すフィールドを単に size とするのではなく、sizeBytes や sizeMegapixels のように単位を明示することで、そのフィールドの意味と使用方法が明確になります。これは、特に異なるシステム間で情報をやり取りする際に重要です。

著者が挙げている火星気候軌道船の例は、単位の不一致がもたらす重大な結果を示す極端な例ですが、日常的な開発においても同様の問題は起こりうます。例えば、あるサービスが秒単位で時間を扱い、別のサービスがミリ秒単位で扱っている場合、単位が明示されていないと深刻なバグの原因となる可能性があります。

Rustにおいて、このような問題に対処するための一つの方法は、カスタム型を使用することです。例えば：

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct Bytes(pub i64);

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct Megapixels(pub f64);

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Dimensions {
    pub width: Megapixels,
    pub height: Megapixels,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Image {
    pub content: Vec<u8>,
    pub size_bytes: Bytes,
    pub dimensions: Dimensions,
}

このようなアプローチは、型安全性を高め、単位の誤用を防ぐのに役立ちます。さらに、これらの型に特定のメソッドを追加することで、単位変換や値の検証を容易に行うことができます。

結論

著者は、良い命名の重要性と、それがAPIの品質全体に与える影響を明確に示しています。良い名前は、可読性だけでなく、APIの使いやすさ、保守性、長期的な進化可能性に直接効いてきます。

マイクロサービスやクラウドネイティブ環境では、表現力・シンプルさ・予測可能性を兼ね備えた名前こそが「システム全体の地図」になります。私は章の内容を受けて、すべてのPRに以下のコメントテンプレートを残すようにしています。

この名前は初見の開発者でも目的を言い当てられるか
既存の命名規則から外れていないか（動詞・ケース・単位）
単位やデータ型の違いを名前で識別できるか

特に、単位やデータ型を明示する名前は、誤用を防ぐ最後の砦です。私はtimeoutという曖昧なフィールド名をtimeoutSecondsにrenameしただけで、サポート問合せが激減しました。Rustの文脈なら、newtype パターンで単位を型として表現しつつ、serdeの#[serde(rename_all = "camelCase")]でJSONフィールド名を自動変換するのが効果的です。

最後に、命名は技術の話であると同時にコミュニケーションの話でもあります。名前の一貫性が、チーム内外の信頼を築き、プロジェクトの成功確率を押し上げます。短期的な工数節約のために命名を手抜きすると、後で必ず清算される――この章は、その厳しい真実を何度も思い出させてくれました。

4 Resource scope and hierarchy

「API Design Patterns」の第4章「Resource scope and hierarchy」は、APIにおけるリソースのスコープと階層構造に焦点を当て、リソースレイアウトの概念、リソース間の関係性の種類、エンティティ関係図の活用方法、適切なリソース関係の選択基準、そしてリソースレイアウトのアンチパターンについて詳細に論じています。この章を通じて、著者はリソース中心のAPI設計の重要性と、それがシステムの拡張性、保守性、そして全体的なアーキテクチャにどのように影響を与えるかを明確に示しています。

私はこの章を読みながら、かつて「とりあえずリソースっぽいURLを並べておけば動くだろう」と雑に設計したユーザー課金APIを思い出しました。親リソースと子リソースの境界を曖昧にした結果、/users/{id}/paymentsと/payments/{id}が同居し、所有権もライフサイクルも説明できなくなって大炎上。結局ぜんぶ作り直す羽目になった苦い記憶があります。

Figure 4.2 Users, payment methods, and addresses all have different relationships to one another. より引用

リソースレイアウトの重要性

著者は、アクションよりもリソースを軸に捉えることがAPIの一貫性と理解しやすさを高めると強調します。マイクロサービスが入り乱れる環境で「このエンドポイントは何の所有物か」が曖昧になると、一瞬で地雷原になります。私は章の内容をもとに、リソースレイアウト検討時の3問チェックを作りました。

親子関係を説明できるか（所有者は誰か、ライフサイクルは一緒か）
URLとリソース名がドメイン言語と一致しているか（users/{id}/cardsなど）
リソース間の境界を図で説明できるか（ERDやリソースマップを必ず描く）

リソースレイアウトは単なるDBスキーマではなく、クライアントとサーバーの契約そのものです。契約が曖昧だと、後から「親の削除で子はどうなるのか」「参照は許されるのか」といった議論が無限に発生します。

リソース間の関係性

著者は、リソース間の関係性を参照・多対多・自己参照・階層の4種類に整理します。私はこの章を読みながら、「関係性を言語化できないまま実装を始めると必ず破綻する」と改めて痛感しました。特に意識しているのは以下の問いです。

参照関係: ただの参照か、それとも所有権を伴うのか？（例: Message.author）
多対多関係: 中間リソースを立てる理由は説明できるか？（例: Membership）
自己参照関係: 階層の深さは制限されているか？（例: Folder -> SubFolder）
階層関係: 親を削除したとき子はどうなるか？（例: users/{id}/cards）

これらを曖昧にしたままリリースし、後から「このカードは誰の所有物？」と議論になったことがあります。以来、設計会議では必ずリソース関係のマトリクスを作り、所有権・参照の種類・ライフサイクルを明文化しています。

例えば、Rustを用いてマイクロサービスを実装する場合、これらの関係性を適切に表現することが重要です。以下は、チャットアプリケーションにおけるメッセージとユーザーの関係を表現する簡単な例です。

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Message {
    pub id: String,
    pub content: String,
    #[serde(rename = "author_id")]
    pub author_id: String,
    pub timestamp: DateTime<Utc>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct User {
    pub id: String,
    pub username: String,
    pub email: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChatRoom {
    pub id: String,
    pub name: String,
    #[serde(rename = "user_ids")]
    pub user_ids: Vec<String>,
}

この例では、MessageがUserを参照する関係性と、ChatRoomとUserの多対多関係を表現しています。

エンティティ関係図の活用

著者は、エンティティ関係図（ERD）の重要性とその読み方について詳しく説明します。私は以前、ERDを描かずにレビューへ投げて「結局このリソースって1対多？多対多？」と突っ込まれ、会議が2時間延びた苦い経験があります。それ以来、設計レビューには必ず以下の2枚を添付しています。

システム全体ERD：サービス単位でリソースの関係とカーディナリティを示す
エンドポイント別リソースマップ：URL、所有権、参照種別を整理した表

ERDは設計フェーズだけでなく、ドキュメントやオンボーディング、障害対応時にも使い回せる万能ツールです。図を描くと「あ、このリソース余計だな」「ここは関連が深すぎるな」という気づきが得られます。

適切な関係性の選択

著者は、リソース間の適切な関係性を選択する際の考慮点について詳細に論じています。押さえておくべきポイントを整理します。

関係性の必要性: すべてのリソース間に関係性を持たせる必要はありません。必要最小限の関係性に留めることで、APIの複雑性を抑制できます。
インライン化 vs 参照: リソースの情報をインライン化するか、参照として扱うかの選択は、パフォーマンスとデータの一貫性のトレードオフを考慮して決定する必要があります。
階層関係の適切な使用: 階層関係は強力ですが、過度に深い階層は避けるべきです。

私はこのリストを見て、「関係性を増やす前に立ち止まる三問」を自分のノートに貼りました。

この関係はプロダクト価値に直結するか？それとも単なる便利機能か？
インライン化で済む情報まで別リソースにしていないか？
階層を1段削っても要件を満たせないか？

これらの問いをクリアできない関係は、将来の足かせになることが多いです。逆に、必要最小限の関係だけを丁寧に作れば、システムの理解も機能追加も一気に楽になります。

アンチパターンの回避

著者は、リソースレイアウトにおける一般的なアンチパターンとその回避方法について説明しています。特に注目すべきアンチパターンは以下の通りです。

全てをリソース化する: 小さな概念まですべてをリソース化することは、APIを不必要に複雑にする可能性があります。
深すぎる階層: 過度に深い階層構造は、APIの使用と理解を困難にします。
全てをインライン化する: データの重複や一貫性の問題を引き起こす可能性があります。

私は以前、/users/{id}/stores/{store_id}/orders/{order_id}/items/{item_id}のような深さ5の階層を平気で作っていました。結果として、クライアント実装はURL生成だけで数百行に膨れ上がり、モック作成も地獄。章で紹介されているアンチパターンを意識するようになってからは、「深さは基本2段まで」をガイドラインに定め、どうしても必要な場合はクエリパラメータやフィルタリングで表現するようにしています。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、マイクロサービスアーキテクチャやクラウドネイティブ環境での応用を考えると、以下のような点が重要になります。

サービス境界の定義: リソースの関係性を適切に設計することで、マイクロサービス間の境界を明確に定義できます。これは、システムの拡張性と保守性に直接的な影響を与えます。
パフォーマンスとスケーラビリティ: インライン化と参照の適切な選択は、システムのパフォーマンスとスケーラビリティに大きく影響します。例えば、頻繁に一緒にアクセスされるデータをインライン化することで、不必要なネットワーク呼び出しを減らすことができます。
進化可能性: 適切にリソースと関係性を設計することで、将来的なAPIの拡張や変更が容易になります。これは、長期的なシステム運用において重要です。

私は章の学びを以下の「リソース設計レビューシート」に落とし込みました。レビュー前に一度自問するだけで、議論の質が大幅に上がります。

リソース一覧とURLが、プロダクトのドメインモデルと一致しているか
各関係性の種類（参照/所有/多対多）が明文化されているか
ERDとAPIドキュメントが同期しているか（更新日も記載する）

リソース設計は、API全体の骨格を決める意思決定です。ここで迷走すると、後続章で扱う命名やデータ型の話も軸がぶれてしまうので、最初に腰を据えて議論する価値があります。

一貫性と予測可能性: リソースレイアウトの一貫したアプローチは、APIの学習曲線を緩やかにし、開発者の生産性を向上させます。
運用の簡素化: 適切に設計されたリソース階層は、アクセス制御やログ分析などの運用タスクを簡素化します。

Rustの文脈では、これらの設計原則を反映したAPIの実装が重要になります。例えば、Rustの構造体やトレイトを使用して、リソース間の関係性を明確に表現することができます。また、Rustの強力な型システムを活用することで、APIの一貫性と型安全性を確保することができます。

結論

第4章「Resource scope and hierarchy」は、APIデザインにおけるリソースのスコープと階層構造の重要性を明確に示しています。適切なリソースレイアウトの設計は、APIの使いやすさ、拡張性、保守性に直接的な影響を与えます。

この章から持ち帰るべき教訓は4つです。

リソース間の関係性を慎重に設計し、必要最小限の関係性に留めること。
インライン化と参照のトレードオフを理解し、適切に選択すること。
階層関係を効果的に使用しつつ、過度に深い階層は避けること。
一般的なアンチパターンを認識し、回避すること。

要するに、APIの設計はシステム全体のアーキテクチャと密接に関連しているということです。リソースレイアウトで楽をすると、後から結合度の高さに泣かされます。

5 Data types and defaults

「API Design Patterns」の第5章「Data types and defaults」は、APIにおけるデータ型とデフォルト値の重要性、各データ型の特性と使用上の注意点、そしてシリアライゼーションの課題について詳細に論じています。この章を通じて、著者はAPIの設計において適切なデータ型の選択とデフォルト値の扱いが、APIの使いやすさ、信頼性、そして長期的な保守性にどのように影響するかを明確に示しています。

データ型の重要性と課題

著者は、APIにおけるデータ型の重要性から議論を始めています。特に注目すべきは、プログラミング言語固有のデータ型に依存せず、シリアライゼーションフォーマット（主にJSON）を介して異なる言語間で互換性のあるデータ表現を実現することの重要性です。この問題は根深すぎて一つの解決策として開発言語を揃えるまでしている組織がある。

この概念を視覚的に表現するために、著者は以下の図を提示しています。

Figure 5.1 Data moving from API server to client より引用

この図は、APIサーバーからクライアントへのデータの流れを示しています。サーバー側でのプログラミング言語固有の表現がシリアライズされ、言語非依存の形式（多くの場合JSON）に変換され、ネットワークを介して送信されます。クライアント側では、このデータがデシリアライズされ、再びクライアントの言語固有の表現に変換されます。

この過程は、マイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。異なる言語やフレームワークで実装された複数のサービスが協調して動作する環境では、このようなデータの変換と伝送が頻繁に行われるため、データ型の一貫性と互換性が不可欠です。例えば、あるサービスが64ビット整数を使用し、別のサービスがそれを32ビット整数として解釈してしまうと、深刻なバグや不整合が発生する可能性があります。

著者が指摘する「null」値と「missing」値の区別も重要な論点です。これは、オプショナルな値の扱いにおいて特に重要で、APIの設計者はこの違いを明確に意識し、適切に処理する必要があります。例えば、Rustにおいては、以下のように構造体のフィールドをOption<T>型にすることで、この区別を表現できます。

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct User {
    pub id: String,
    pub name: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub age: Option<i32>,
    #[serde(rename = "is_active", skip_serializing_if = "Option::is_none")]
    pub is_active: Option<bool>,
}

この設計により、ageやis_activeフィールドが省略された場合（missing）と、明示的にnullが設定された場合を区別できます。私は以前、この区別を怠ったままリリースし、「nullは値を消したい意図なのか、単なるフィールド欠落なのか？」とサポートチャネルで延々と質問を受けました。章で紹介されているように、Option<T>や#[serde(skip_serializing_if = "Option::is_none")]を使って二つの状態を明示するだけで、後の誤解をかなり防げます。

プリミティブデータ型の扱い

著者は、ブール値・数値・文字列といったプリミティブ型の扱いこそがAPIの信頼性を決めると説きます。私は以下のミニチェックリストをPRレビューに貼り付けています。

ブール値: 二重否定になっていないか？allowChatbotsのように肯定形で表現できないか？
数値: 64ビットを超える可能性は？JavaScriptクライアントに備えて文字列でシリアライズできるか？
文字列: エンコードと正規化（NFCなど）を明記したか？比較の前に正規化が必要か？

数値に関しては、大きな整数や浮動小数点の扱いに注意が必要です。著者が推奨するように文字列でシリアライズしておくと、言語間差異によるバグを避けられます。私は一度、JavaScriptでIEEE754誤差にハマり、会計システムの残高を1円ずつ狂わせてしまいました……。

use serde::{Deserialize, Deserializer, Serialize};

#[derive(Debug, Clone, Serialize)]
pub struct LargeNumber {
    pub value: String,
}

impl<'de> Deserialize<'de> for LargeNumber {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        // ここで文字列を適切な数値型に変換
        // エラーチェックも行う
        Ok(LargeNumber { value: s })
    }
}

文字列に関しては、UTF-8 エンコーディングの使用と、正規化形式（特にNFC）の重要性が強調されています。これは特に識別子として使用される文字列に重要で、一貫性のある比較を保証します。

コレクションと構造体

著者は、リスト（配列）とマップ（オブジェクト）についても詳細に論じています。これらのデータ型は、複雑なデータ構造を表現する上で不可欠ですが、適切に使用しないと問題を引き起こす可能性があります。

リストを導入する時は「最大要素数はいくつか」「順序に意味があるか」「空リストとnullを区別するか」を必ず決めています。マップについても「キーにどんな制約を設けるか」「既存スキーマとどう整合させるか」を明記しないと、後から誰も検証できません。

実践的な応用と考察

私はこの章を読み終えたあと、データ型レビュー用のショートリストを作りました。マイクロサービスやクラウドネイティブ環境で意識すべきポイントは以下の通りです。

データの一貫性: 日時はISO 8601、金額はDecimalStringなど、フォーマットを全サービスで統一する。フォーマットを変えたくなったらメジャーバージョンを検討する。
バージョニング: データ型を変える時は互換性マトリクスを作成し、既存クライアントへの影響を可視化してからリリースプランを引く。
パフォーマンス: リストやマップにはハードな制限を設け、制限値をレスポンスヘッダにも載せる。ログ監視で制限超過を検知する。
エラーハンドリング: データ型違反時のエラーメッセージに「期待する型」「最大長」「例」を載せる。私のチームではINVALID_ARGUMENTを返すときに必ずdetailsで具体値を返すようにしています。
ドキュメンテーション: スキーマに制約と単位を必ず記載し、Swaggerやopenapiに反映させる。ドキュメント更新日を入れておかないと、古い仕様のまま議論してしまうので注意。

Rustの文脈では、これらの設計原則を反映したAPIの実装が重要になります。例えば、serdeのDeserializeトレイトをカスタム実装して、文字列として受け取った大きな数値を適切に処理することができます。また、Rustの強力な型システムを活用することで、APIの型安全性を高めることができます。

use serde::{Deserialize, Deserializer, Serialize, Serializer};

#[derive(Debug, Clone, Copy)]
pub struct SafeInt64(pub i64);

impl Serialize for SafeInt64 {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(&self.0.to_string())
    }
}

impl<'de> Deserialize<'de> for SafeInt64 {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        let i = s.parse::<i64>().map_err(serde::de::Error::custom)?;
        Ok(SafeInt64(i))
    }
}

結論

第5章「Data types and defaults」は、APIデザインにおけるデータ型とデフォルト値の重要性を明確に示しています。適切なデータ型の選択と、それらの一貫した使用は、APIの使いやすさ、信頼性、そして長期的な保守性に直接的な影響を与えます。

要点を5つ挙げます。

プログラミング言語に依存しない、一貫したデータ表現の重要性。
null値とmissing値の区別、およびそれらの適切な処理。
大きな数値や浮動小数点数の安全な取り扱い。
文字列のエンコーディングと正規化の重要性。
コレクション（リストとマップ）の適切な使用とサイズ制限。

私がfloatで金額を扱ったとき、請求書に1円のズレが出た。原因究明に3日かかり、修正後の互換性確保にさらに1週間。データ型の選択ミスは、後から直すコストが桁違いに高い。特にJavaScriptとの連携では、53ビットを超える整数が静かに壊れる。「とりあえずnumber」で済ませた過去の自分を殴りたい。

Part 3 Fundamentals

このパートでは、APIの基本的な操作と機能について深く掘り下げています。標準メソッド（GET、POST、PUT、DELETE等）の適切な使用法、部分的な更新と取得、カスタムメソッドの設計、長時間実行操作の扱い方などが説明されています。これらの基本的な要素を適切に設計することで、APIの使いやすさと機能性が大きく向上します。

6 Resource identification

「API Design Patterns」の第6章「Resource identification」は、APIにおけるリソース識別子の重要性、良い識別子の特性、その実装方法、そしてUUIDとの関係について詳細に論じています。連番IDで油断していた頃の自分を思い出し、胃がキュッとなりました。識別子は「どうでもいい技術的詳細」ではなく、API全体の信頼性と運用効率を左右する契約そのものです。

識別子の重要性と特性

著者は、良い識別子の特性として「使いやすさ・一意性・永続性・生成容易さ・予測不可能性・読みやすさ/検証可能性・情報密度」を挙げます。私はこれをそのまま「IDレビュー七箇条」にしました。設計レビューでは以下を必ず確認します。

予測可能な連番や日時ベースのIDになっていないか
生成コストが高すぎてレスポンスに影響しないか
人間がログで追えるか（読みやすさ、チェックサム）

このチェックを追加してから、ID設計で痛い目を見ることが格段に減りました。

著者が提案する識別子の形式は、Crockford's Base32エンコーディングを使用したものです。この選択には多くの利点があります。

高い情報密度（ASCIIキャラクタあたり5ビット）
人間が読みやすく、口頭でも伝えやすい
大文字小文字を区別しない柔軟性
チェックサム文字による検証可能性

これらの特性は、実際の運用環境で有用です。例えば、識別子の読み上げやタイプミスの検出が容易になり、サポートや障害対応の効率が向上します。

実装の詳細

著者は、識別子の実装に関して詳細なガイダンスを提供しています。特に注目すべき点は以下の通りです。

サイズの選択: 著者は、用途に応じて64ビットまたは128ビットの識別子を推奨しています。これは、多くのユースケースで十分な一意性を提供しつつ、効率的なストレージと処理を可能にします。
生成方法: 暗号学的に安全な乱数生成器の使用を推奨しています。これは、識別子の予測不可能性と一意性を確保する上で重要です。
チェックサムの計算: 識別子の検証を容易にするためのチェックサム文字の追加方法を詳細に説明しています。
データベースでの保存: 文字列、バイト列、整数値としての保存方法を比較し、それぞれの利点と欠点を分析しています。

これらの実装詳細は、実際のシステム設計において有用です。例えば、Rustでの実装を考えると、以下のようなコードが考えられます。

use base32::Alphabet;
use rand::RngCore;
use thiserror::Error;

#[derive(Error, Debug)]
pub enum IdError {
    #[error("failed to generate random bytes")]
    RandomError,
}

pub fn generate_id() -> Result<String, IdError> {
    let mut bytes = [0u8; 16]; // 128ビットの識別子
    rand::thread_rng()
        .try_fill_bytes(&mut bytes)
        .map_err(|_| IdError::RandomError)?;

    let encoded = base32::encode(Alphabet::Rfc4648 { padding: false }, &bytes);
    let checksum = calculate_checksum(&bytes);
    Ok(format!("{}{}", encoded, checksum_char(checksum)))
}

fn calculate_checksum(bytes: &[u8]) -> usize {
    bytes.iter().map(|&b| b as usize).sum::<usize>() % 32
}

fn checksum_char(checksum: usize) -> char {
    (b'A' + checksum as u8) as char
}

fn main() {
    match generate_id() {
        Ok(id) => println!("Generated ID: {}", id),
        Err(e) => eprintln!("Error generating ID: {}", e),
    }
}

このような実装は、安全で効率的な識別子生成を可能にし、システムの信頼性と拡張性を向上させます。

識別子の階層と一意性のスコープ

著者は、識別子の階層構造と一意性のスコープについても詳細に論じています。階層IDを導入する前に以下の問いを投げかけると、後悔が減ります。

親から独立しても子のIDを保てるか？
親の所有者が変わったとき、IDも変わってしまわないか？
フラットなID＋参照フィールドで表現できないか？

私はかつて/users/{id}/cards/{card_id}をそのまま永続IDにしたせいで、カードの譲渡要件が出た瞬間に全データを再発行せざるを得ませんでした。真の所有権関係がある場合にだけ階層を使う――この原則は絶対に忘れないよう心がけています。

UUIDとの比較

著者は、提案する識別子形式とUUIDを比較し、ユースケースに応じた使い分けを勧めています。私は次のように整理しました。

Base32＋チェックサム方式: 人間が扱う場面（サポート、CLI）で強い。読みやすさと検証性が必要なときはこちら。
UUID v4: 分散環境で大量生成し、衝突リスクを最低限にしたいとき。人間が読む必要がない内部API向け。
Snowflake系（時系列ベース）: 並び順で意味を持たせたい場合やバッチ処理で便利。時計ずれのリスクを受け入れられるなら選択肢になる。

システム要件を確認したうえで、適切な識別子形式を選ぶことが重要です。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

スケーラビリティと性能: 適切な識別子の設計は、システムのスケーラビリティと性能に直接影響します。例えば、128ビットの識別子を使用することで、将来的な成長に対応しつつ、効率的なインデックスの作成が可能になります。
セキュリティ: 予測不可能な識別子の使用は、リソースの推測や不正アクセスを防ぐ上で重要です。これは、特に公開APIにおいて重要な考慮事項です。
運用性: 人間が読みやすく、検証可能な識別子は、デバッグやトラブルシューティングを容易にします。これは、大規模なシステムの運用において有用です。
バージョニングとの関係: 識別子の設計は、APIのバージョニング戦略と密接に関連しています。永続的で一意な識別子は、異なるバージョン間でのリソースの一貫性を維持するのに役立ちます。
データベース設計: 識別子の形式と保存方法の選択は、データベースの性能と拡張性に大きな影響を与えます。著者の提案する形式は、多くのデータベースシステムで効率的に扱うことができます。

結論

第6章「Resource identification」は、APIにおけるリソース識別子の重要性と、その適切な設計の必要性を明確に示しています。著者の提案する識別子形式は、使いやすさ、安全性、効率性のバランスが取れており、多くのユースケースで有用です。

核心は5点に集約されます。

識別子は単なる技術的詳細ではなく、APIの使いやすさと信頼性に直接影響を与える重要な設計上の決定である。
良い識別子は、一意性、永続性、予測不可能性、読みやすさなど、複数の重要な特性を兼ね備えている必要がある。
Crockford's Base32エンコーディングの使用は、多くの利点をもたらす。
識別子の階層構造は慎重に設計する必要があり、真の「所有権」関係がある場合にのみ使用すべきである。
UUIDは広く採用されているが、特定のユースケースでは著者の提案する形式の方が適している場合がある。

これらの原則を適切に適用すれば、開発者にとって使いやすく、長期的に保守可能なAPIを設計できます。私は章を読み終えて、識別子設計のレビューシートに次の三箇条を書き込みました。

契約としてのID: 一度発行したIDは変えない。永続性と一意性を最優先。
不可視化: 推測可能なIDは禁止。公開APIでは連番や短い整数を避ける。
可観測性: 人間がたどれる形式を選び、チェックサムでタイプミスを即検知できるようにする。

識別子の設計はシステム全体のアーキテクチャと直結します。ここで妥協すると、後続のバージョニングや運用全体でツケを払うことになります。早い段階で方針を決め、レビューとドキュメントで徹底しましょう。

7 Standard methods

「API Design Patterns」の第7章「Standard methods」は、APIにおける標準メソッドの重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者は標準メソッドが単なる慣習ではなく、APIの一貫性、予測可能性、そして使いやすさを大きく向上させる重要な設計上の決定であることを明確に示しています。

標準メソッドの重要性と概要

著者は、標準メソッドの重要性から議論を始めています。APIの予測可能性を高めるために、リソースごとに異なる操作を定義するのではなく、一貫した標準メソッドのセットを定義することの利点を強調しています。具体的には、以下の標準メソッドが紹介されています。

Get：既存のリソースを取得
List：リソースのコレクションをリスト化
Create：新しいリソースを作成
Update：既存のリソースを更新
Delete：既存のリソースを削除
Replace：リソース全体を置き換え

HTTP には他にもいくつかのメソッドが用意されている

en.wikipedia.org

これらの標準メソッドは、RESTful APIの設計原則に基づいており、多くの開発者にとって馴染みのある概念です。しかし、著者はこれらのメソッドの実装に関する詳細な指針を提供することで、単なる慣習を超えた、一貫性のある強力なAPI デザインパターンを提示しています。

この標準化されたアプローチは、マイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。複数のサービスが協調して動作する環境では、各サービスのインターフェースが一貫していることが、システム全体の理解と保守を容易にします。例えば、全てのサービスで同じ標準メソッドを使用することで、開発者はサービス間の相互作用をより直感的に理解し、新しいサービスの統合や既存のサービスの修正をスムーズに行うことができます。

私は最初のマイクロサービス群を構築した際、「ここは特殊だから」と独自メソッドを乱立させ、ProvisionUserやRemoveUserCompletelyのような謎メソッドが大量に生まれました。新メンバーは毎回ドキュメントを読み直さなければならず、サポートの質問も増大。結局、後からすべてをGet/List/Create/Update/Delete/Replaceに整理する大工事を経験しました。

実装の詳細とベストプラクティス

著者は、各標準メソッドの実装に関して詳細なガイダンスを提供しています。私は以下のチェックリストをPRコメントに貼り、各メソッドを見直すようにしています。

べき等性: Get/Listは完全に副作用ゼロか？Update/Deleteのべき等性をどう扱うか。
一貫性: Create直後にGet/Listで即座に見えるか。結果整合性の遅延は許容範囲か。
部分更新 vs 全置換: PATCHとPUTを明確に分け、API利用者の混乱を防いでいるか。
削除の語義: Deleteは物理削除かソフト削除か。べき等かどうかを仕様に記載しているか。

use async_trait::async_trait;
use std::collections::HashMap;

#[async_trait]
pub trait ResourceService {
    async fn get(&self, id: &str) -> Result<Resource, Error>;
    async fn list(&self, filter: &str) -> Result<Vec<Resource>, Error>;
    async fn create(&self, resource: &Resource) -> Result<Resource, Error>;
    async fn update(&self, id: &str, updates: HashMap<String, serde_json::Value>) -> Result<Resource, Error>;
    async fn replace(&self, id: &str, resource: &Resource) -> Result<Resource, Error>;
    async fn delete(&self, id: &str) -> Result<(), Error>;
}

このようなトレイトは、標準メソッドの一貫した実装を促進し、APIの使いやすさと保守性を向上させます。

標準メソッドの適用と課題

著者は、標準メソッドを適用する際の注意点も挙げています。私が実務で目を光らせているポイントは次の通りです。

メソッドの選択: すべてのリソースが全メソッドを持つ必要はない。リソース特性を整理してから余計なメソッドを削る。
アクセス制御: ListやGetにRBAC/ABACをどう組み込むか。ユーザーごとに返す内容が違う場合、レスポンスのキャッシュ戦略も再検討する。
カウント/ソート: Listで気軽に?sort=...&count=trueを提供しない。重い操作は別のエンドポイントか非同期処理に逃がす。
フィルタリング: 構造化されたクエリ言語を導入するのか、文字列ベースにするのか。DSLを作るならテストと検証ロジックをセットで提供する。

これらの考慮点は、特に大規模なシステムやマイクロサービスアーキテクチャにおいて重要です。例えば、Listメソッドでのカウントやソートの制限は、システムの水平スケーリング能力を維持する上で重要です。同様に、柔軟なフィルタリングの実装は、APIの長期的な進化と拡張性を確保します。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

一貫性と予測可能性: 標準メソッドを一貫して適用することで、APIの学習曲線が緩やかになり、開発者の生産性が向上します。これは、特に大規模なシステムや多くのマイクロサービスを持つ環境で重要です。
パフォーマンスとスケーラビリティ: 著者の推奨事項（例：Listメソッドでのカウントやソートの制限）は、システムのパフォーマンスとスケーラビリティを維持する上で重要です。これらの原則を適用することで、システムの成長に伴う課題を予防できます。
バージョニングとの関係: 標準メソッドの一貫した実装は、APIのバージョニング戦略とも密接に関連します。新しいバージョンを導入する際も、これらの標準メソッドの挙動を維持することで、後方互換性を確保しやすくなります。
セキュリティの考慮: 標準メソッドの実装において、適切なアクセス制御やエラーハンドリングを行うことは、APIのセキュリティを確保する上で重要です。
運用性: 標準メソッドの一貫した実装は、監視、ログ記録、デバッグなどの運用タスクを簡素化します。これにより、問題の迅速な特定と解決が可能になります。

結論

第7章「Standard methods」は、APIにおける標準メソッドの重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの一貫性、予測可能性、使いやすさを大きく向上させる可能性があります。

私が標準メソッドのレビューで必ず確認している5点がある。

Get/List/Create/Update/Delete/Replaceの命名と振る舞いが、既存APIと揃っているか
べき等性の有無を仕様に明記しているか（特にUpdate/Delete）
Create直後にGetで取得できる強い一貫性を保証しているか
各メソッドのパフォーマンス特性（N+1など）を意識しているか
運用チームがログから「何が起きたか」を追えるか

「DELETE は本当に消すのか、論理削除か」を曖昧にしたまま3チームが実装を進め、結合テストで地獄を見たことがある。標準メソッドの意味を最初に合意しておかないと、後から「うちのDELETEは違う」という言い訳が横行する。RESTの「標準」は、チーム間の方言を減らすためにある。

8 Partial updates and retrievals

「API Design Patterns」の第8章「Partial updates and retrievals」は、APIにおける部分的な更新と取得の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者は部分的な更新と取得が単なる機能の追加ではなく、APIの柔軟性、効率性、そして長期的な使いやすさに直接影響を与える重要な設計上の決定であることを明確に示しています。

部分的な更新と取得の動機

著者は、部分的な更新と取得の必要性から議論を始めています。特に、大規模なリソースや制限のあるクライアント環境での重要性を強調しています。例えば、IoTデバイスのような制限された環境では、必要最小限のデータのみを取得することが重要です。また、大規模なリソースの一部のみを更新する必要がある場合、全体を置き換えるのではなく、特定のフィールドのみを更新する能力が重要になります。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、複数のマイクロサービスが協調して動作する環境では、各サービスが必要とするデータのみを効率的に取得し、更新することが、システム全体のパフォーマンスとスケーラビリティを向上させます。

著者は、部分的な更新と取得を実現するためのツールとしてフィールドマスクの概念を導入しています。フィールドマスクは、クライアントが関心のあるフィールドを指定するための単純かつ強力なメカニズムです。これにより、APIは必要なデータのみを返すか、指定されたフィールドのみを更新することができます。

フィールドマスクの実装

著者は、フィールドマスクの実装に関して詳細なガイダンスを提供しています。特に注目すべき点は以下の通りです。

トランスポート: フィールドマスクをどのようにAPIリクエストに含めるかについて議論しています。著者は、クエリパラメータを使用することを推奨しています。これは、HTTPヘッダーよりもアクセスしやすく、操作しやすいためです。
ネストされたフィールドとマップの扱い: 著者は、ドット表記を使用してネストされたフィールドやマップのキーを指定する方法を説明しています。これにより、複雑なデータ構造でも柔軟に部分的な更新や取得が可能になります。
繰り返しフィールドの扱い: 配列やリストのような繰り返しフィールドに対する操作の制限について議論しています。著者は、インデックスベースの操作を避け、代わりにフィールド全体の置き換えを推奨しています。
デフォルト値: 部分的な取得と更新におけるデフォルト値の扱いについて説明しています。特に、更新操作での暗黙的なフィールドマスクの使用を推奨しています。

これらの実装詳細は、実際のシステム設計において有用です。例えば、Rustでの実装を考えると、以下のようなコードが考えられます。

use serde::{Deserialize, Serialize};

pub type FieldMask = Vec<String>;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UpdateUserRequest {
    pub user: User,
    #[serde(rename = "fieldMask", skip_serializing_if = "Option::is_none")]
    pub field_mask: Option<FieldMask>,
}

pub async fn update_user(req: &mut UpdateUserRequest) -> Result<User, Error> {
    let mut existing_user = get_user_from_database(&req.user.id).await?;

    let field_mask = req.field_mask.clone().unwrap_or_else(|| infer_field_mask(&req.user));

    for field in &field_mask {
        match field.as_str() {
            "name" => existing_user.name = req.user.name.clone(),
            "email" => existing_user.email = req.user.email.clone(),
            // ... その他のフィールド
            _ => {}
        }
    }

    save_user_to_database(&existing_user).await
}

fn infer_field_mask(user: &User) -> FieldMask {
    let mut mask = Vec::new();
    if !user.name.is_empty() {
        mask.push("name".to_string());
    }
    if !user.email.is_empty() {
        mask.push("email".to_string());
    }
    // ... その他のフィールド
    mask
}

このコードでは、フィールドマスクを明示的に指定しない場合、提供されたデータから暗黙的にフィールドマスクを推論しています。これにより、クライアントは必要なフィールドのみを更新でき、不要なデータの送信を避けることができます。

部分的な更新と取得の課題

著者は、部分的な更新と取得の実装に関する重要な課題についても議論しています。

一貫性: 部分的な更新を行う際、リソース全体の一貫性を維持することが重要です。特に、相互に依存するフィールドがある場合、この点に注意が必要です。
パフォーマンス: フィールドマスクの解析と適用には計算コストがかかります。大規模なシステムでは、このオーバーヘッドを考慮する必要があります。
バージョニング: APIの進化に伴い、新しいフィールドが追加されたり、既存のフィールドが変更されたりする可能性があります。フィールドマスクの設計は、このような変更に対応できる柔軟性を持つ必要があります。
セキュリティ: フィールドマスクを通じて、クライアントがアクセスを許可されていないフィールドを更新または取得しようとする可能性があります。適切なアクセス制御が必要です。

これらの課題は、特に大規模なシステムや長期的に維持されるAPIにおいて重要です。例えば、マイクロサービスアーキテクチャでは、各サービスが扱うデータの一部のみを更新する必要がある場合がしばしばあります。この時、部分的な更新機能は有用ですが、同時にサービス間のデータ整合性を維持することが重要になります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

効率性とパフォーマンス: 部分的な更新と取得を適切に実装することで、ネットワーク帯域幅の使用を最適化し、システム全体のパフォーマンスを向上させることができます。これは特に、モバイルアプリケーションや帯域幅が制限されている環境で重要です。
柔軟性と拡張性: フィールドマスクを使用することで、APIの柔軟性が大幅に向上します。クライアントは必要なデータのみを要求でき、新しいフィールドの追加も既存のクライアントに影響を与えずに行えます。
バージョニングとの関係: 部分的な更新と取得は、APIのバージョニング戦略と密接に関連しています。新しいバージョンを導入する際も、フィールドマスクを通じて後方互換性を維持しやすくなります。
運用性と可観測性: 部分的な更新と取得を適切に実装することで、システムの運用性が向上します。例えば、特定のフィールドの更新頻度や、どのフィールドが最も頻繁に要求されるかを監視することで、システムの使用パターンをより深く理解し、最適化の機会を見出すことができます。
エラーハンドリング: 無効なフィールドマスクや、存在しないフィールドへのアクセス試行をどのように処理するかは重要な設計上の決定です。適切なエラーメッセージと状態コードを返すことで、APIの使いやすさと信頼性を向上させることができます。

フィールドマスクの高度な使用法

著者は、フィールドマスクのより高度な使用法についても言及しています。特に注目すべきは、ネストされた構造やマップ型のフィールドへの対応です。

例えば、次のような複雑な構造を持つリソースを考えてみましょう：

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct User {
    pub id: String,
    pub name: String,
    pub address: Address,
    pub settings: HashMap<String, serde_json::Value>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Address {
    pub street: String,
    pub city: String,
    pub country: String,
}

このような構造に対して、著者は以下のようなフィールドマスクの表記を提案しています。

name: ユーザーの名前を更新または取得
address.city: ユーザーの住所の都市のみを更新または取得
settings.theme: 設定マップ内のテーマ設定のみを更新または取得

この表記法により、非常に細かい粒度で更新や取得を行うことが可能になります。これは特に、大規模で複雑なリソースを扱う場合に有用です。

しかし、このような複雑なフィールドマスクの実装には課題もあります。特に、セキュリティとパフォーマンスの観点から注意が必要です。例えば、深くネストされたフィールドへのアクセスを許可することで、予期せぬセキュリティホールが生まれる可能性があります。また、非常に複雑なフィールドマスクの解析と適用は、システムに大きな負荷をかける可能性があります。

これらの課題に対処するため、著者は以下のような推奨事項を提示しています。

フィールドマスクの深さに制限を設ける
特定のパターンのみを許可するホワイトリストを実装する
フィールドマスクの複雑さに応じて、リクエストのレート制限を調整する

これらの推奨事項は、システムの安全性と性能を確保しつつ、APIの柔軟性を維持するのに役立ちます。

部分的な更新と取得の影響

部分的な更新と取得の実装は、システム全体に広範な影響を与えます。特に以下の点が重要です。

データベース設計: 部分的な更新をサポートするためには、データベースの設計も考慮する必要があります。例えば、ドキュメント指向のデータベースは、部分的な更新に適している場合があります。
キャッシング戦略: 部分的な取得をサポートする場合、キャッシング戦略も再考する必要があります。フィールドごとに異なるキャッシュ期間を設定したり、部分的な更新があった場合にキャッシュを適切に無効化する仕組みが必要になります。
監視とロギング: 部分的な更新と取得をサポートすることで、システムの監視とロギングの複雑さが増します。どのフィールドが更新されたか、どのフィールドが要求されたかを追跡し、適切にログを取ることが重要になります。
ドキュメンテーション: フィールドマスクの使用方法や、各フィールドの意味、相互依存関係などを明確にドキュメント化する必要があります。これにより、API利用者が部分的な更新と取得を適切に使用できるようになります。
テスト戦略: 部分的な更新と取得をサポートすることで、テストケースの数が大幅に増加します。全ての有効なフィールドの組み合わせをテストし、不正なフィールドマスクに対する適切なエラーハンドリングを確認する必要があります。
クライアントライブラリ: APIクライアントライブラリを提供している場合、フィールドマスクを適切に扱えるように更新する必要があります。これにより、API利用者がより簡単に部分的な更新と取得を利用できるようになります。
パフォーマンスチューニング: 部分的な更新と取得は、システムのパフォーマンスに大きな影響を与える可能性があります。フィールドマスクの解析や適用のパフォーマンスを最適化し、必要に応じてインデックスを追加するなどの対策が必要になる場合があります。
セキュリティ対策: フィールドマスクを通じて、機密情報へのアクセスが可能になる可能性があります。適切なアクセス制御と認可チェックを実装し、セキュリティ監査を行うことが重要です。
バージョニング戦略: 新しいフィールドの追加や既存フィールドの変更を行う際、フィールドマスクとの互換性を維持する必要があります。これは、APIのバージョニング戦略に大きな影響を与える可能性があります。
開発者教育: 開発チーム全体が部分的な更新と取得の概念を理解し、適切に実装できるようにするための教育が必要になります。これには、ベストプラクティスの共有やコードレビューのプロセスの更新が含まれる可能性があります。

これらの影響を適切に管理することで、部分的な更新と取得の実装による利点を最大限に活かしつつ、潜在的な問題を最小限に抑えることができます。システム全体のアーキテクチャ、開発プロセス、運用プラクティスを包括的に見直し、必要に応じて調整を行うことが重要です。

最終的に、部分的な更新と取得の実装は、APIの使いやすさと効率性を大幅に向上させる可能性がありますが、同時にシステムの複雑性も増加させます。したがって、その導入を決定する際は、利点とコストを慎重に検討し、システムの要件と制約に基づいて適切な判断を下す必要があります。長期的な保守性、スケーラビリティ、そして全体的なシステムのパフォーマンスを考慮に入れた上で、部分的な更新と取得の実装範囲と方法を決定することが賢明です。

結論

第8章「Partial updates and retrievals」は、APIにおける部分的な更新と取得の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの効率性、柔軟性、そして長期的な保守性を大きく向上させる可能性があります。

実装で押さえるべきポイントは4つです。

部分的な更新と取得は、大規模なリソースや制限のあるクライアント環境で特に重要です。
フィールドマスクは、部分的な更新と取得を実現するための強力なツールです。
適切な実装は、ネットワーク帯域幅の使用を最適化し、システム全体のパフォーマンスを向上させます。
フィールドマスクの使用は、APIの柔軟性と拡張性を大幅に向上させます。
部分的な更新と取得の実装には、一貫性、パフォーマンス、バージョニング、セキュリティなどの課題があり、これらを適切に考慮する必要があります。

部分更新を許可しなかったAPIで、毎回100KBのJSONを往復させていた時期がある。モバイルクライアントから「遅い」とクレームが来て初めて、フィールドマスクの価値を理解した。帯域とレイテンシは、実装の手間より高くつく。

9 Custom methods

「API Design Patterns」の第9章「Custom methods」は、APIにおけるカスタムメソッドの重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はカスタムメソッドが単なる追加機能ではなく、APIの柔軟性、表現力、そして長期的な保守性に直接影響を与える重要な設計上の決定であることを明確に示しています。

カスタムメソッドの必要性と動機

著者は、標準メソッドだけでは対応できないシナリオが存在することから議論を始めています。例えば、電子メールの送信やテキストの翻訳のような特定のアクションをAPIでどのように表現するべきかという問題を提起しています。これらのアクションは、標準的なCRUD操作（Create, Read, Update, Delete）には簡単に当てはまらず、かつ重要な副作用を伴う可能性があります。

この問題は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。複数のサービスが協調して動作する環境では、各サービスが提供する機能が複雑化し、標準的なRESTful操作だけではカバーしきれないケースが増えています。例えば、ある特定の条件下でのみ実行可能な操作や、複数のリソースに跨がる操作などが該当します。

著者は、このような状況に対処するためのソリューションとしてカスタムメソッドを提案しています。カスタムメソッドは、標準メソッドの制約を超えて、APIに特化した操作を実現する手段となります。

カスタムメソッドの実装

カスタムメソッドの実装に関して、著者はいくつかの重要なポイントを強調しています。

HTTP メソッドの選択: カスタムメソッドはほとんどの場合、POSTメソッドを使用します。これは、POSTがリソースの状態を変更する操作に適しているためです。
URL構造: カスタムメソッドのURLは、標準的なリソースパスの後にコロン（:）を使用して、カスタムアクションを示します。例えば、POST /rockets/1234:launchのような形式です。
命名規則: カスタムメソッドの名前は、標準メソッドと同様に動詞+名詞の形式を取るべきです。例えば、LaunchRocketやSendEmailなどです。

これらの規則は、APIの一貫性と予測可能性を維持する上で重要です。特に、大規模なシステムや長期的に運用されるAPIにおいて、この一貫性は開発者の生産性と学習曲線に大きな影響を与えます。

著者が提示する実装例を、Rustを用いて具体化すると以下のようになります。

use async_trait::async_trait;
use serde::{Deserialize, Serialize};

#[async_trait]
pub trait RocketApi {
    async fn launch_rocket(&self, req: &LaunchRocketRequest) -> Result<Rocket, Error>;
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LaunchRocketRequest {
    pub id: String,
}

impl RocketService {
    pub async fn launch_rocket(&self, req: &LaunchRocketRequest) -> Result<Rocket, Error> {
        // カスタムロジックの実装
        // 例: ロケットの状態チェック、打ち上げシーケンスの開始など
        todo!()
    }
}

このような実装により、標準的なCRUD操作では表現しきれない複雑なビジネスロジックを、明確で直感的なAPIインターフェースとして提供することが可能になります。

副作用の取り扱い

カスタムメソッドの重要な特徴の一つとして、著者は副作用の許容を挙げています。標準メソッドが基本的にリソースの状態変更のみを行うのに対し、カスタムメソッドはより広範な操作を行うことができます。例えば、メールの送信、バックグラウンドジョブの開始、複数リソースの更新などです。

この特性は、システムの設計と運用に大きな影響を与えます。副作用を伴う操作は、システムの一貫性や信頼性に影響を与える可能性があるため、慎重に設計する必要があります。例えば、トランザクション管理、エラーハンドリング、リトライメカニズムなどを考慮する必要があります。

著者が提示する電子メール送信の例は、この点を明確に示しています。メールの送信操作は、データベースの更新だけでなく、外部のSMTPサーバーとの通信も含みます。このような複合的な操作をカスタムメソッドとして実装することで、操作の意図を明確に表現し、同時に必要な副作用を適切に管理することができます。

リソースvs.コレクション

著者は、カスタムメソッドを個々のリソースに適用するか、リソースのコレクションに適用するかという選択についても論じています。この選択は、操作の性質と影響範囲に基づいて行われるべきです。

例えば、単一のメールを送信する操作は個々のリソースに対するカスタムメソッドとして実装される一方で、複数のメールをエクスポートする操作はコレクションに対するカスタムメソッドとして実装されるべきです。

この区別は、APIの論理的構造と使いやすさに直接影響します。適切に設計されたカスタムメソッドは、複雑な操作を直感的なインターフェースで提供し、クライアント側の実装を簡素化します。

ステートレスカスタムメソッド

著者は、ステートレスなカスタムメソッドについても言及しています。これらは、永続的な状態変更を伴わず、主に計算や検証を行うメソッドです。例えば、テキスト翻訳やメールアドレスの検証などが該当します。

ステートレスメソッドは、特にデータプライバシーやセキュリティの要件が厳しい環境で有用です。例えば、GDPR（一般データ保護規則）のようなデータ保護規制に対応する必要がある場合、データを永続化せずに処理できるステートレスメソッドは有効なソリューションとなります。

しかし、著者は完全にステートレスなアプローチの限界についても警告しています。多くの場合、将来的にはある程度の状態管理が必要になる可能性があるため、完全にステートレスな設計に固執することは避けるべきだと指摘しています。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

柔軟性と表現力: カスタムメソッドを適切に使用することで、APIの柔軟性と表現力が大幅に向上します。複雑なビジネスロジックや特殊なユースケースを、直感的で使いやすいインターフェースとして提供することが可能になります。
マイクロサービスアーキテクチャとの親和性: カスタムメソッドは、マイクロサービスアーキテクチャにおいて特に有用です。各サービスが提供する特殊な機能や、サービス間の複雑な相互作用を表現するのに適しています。
運用性と可観測性: カスタムメソッドの導入は、システムの運用性と可観測性に影響を与えます。副作用を伴う操作や、複雑な処理フローを含むカスタムメソッドは、適切なログ記録、モニタリング、トレーシングの実装が不可欠です。
バージョニングと後方互換性: カスタムメソッドの追加や変更は、APIのバージョニング戦略に影響を与えます。新しいカスタムメソッドの導入や既存メソッドの変更を行う際は、後方互換性の維持に注意を払う必要があります。
セキュリティの考慮: カスタムメソッド、特に副作用を伴うものは、適切なアクセス制御と認可チェックが必要です。また、ステートレスメソッドを使用する場合でも、入力データの検証やサニタイズは不可欠です。
パフォーマンスとスケーラビリティ: カスタムメソッドの実装は、システムのパフォーマンスとスケーラビリティに影響を与える可能性があります。特に、複雑な処理や外部サービスとの連携を含むメソッドは、適切なパフォーマンスチューニングとスケーリング戦略が必要になります。

結論

第9章「Custom methods」は、APIにおけるカスタムメソッドの重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性、表現力、そして長期的な保守性を大きく向上させる可能性があります。

カスタムメソッドを導入する際の判断基準を整理します。

カスタムメソッドは、標準メソッドでは適切に表現できない複雑な操作や特殊なユースケースに対応するための強力なツールです。
カスタムメソッドの設計と実装には、一貫性のある命名規則とURL構造の使用が重要です。
副作用を伴うカスタムメソッドの使用は慎重に行い、適切な管理と文書化が必要です。
リソースとコレクションに対するカスタムメソッドの適用は、操作の性質に基づいて適切に選択する必要があります。
ステートレスなカスタムメソッドは有用ですが、将来的な拡張性を考慮して設計する必要があります。

カスタムメソッドを乱発して「俺たちのREST」を作ったことがある。半年後、新メンバーが「このAPIのドキュメントどこですか」と聞いてきたとき、答えられなかった。標準から外れるなら、外れる理由を説明できる状態を維持する責任がセットで付いてくる。

10 Long-running operations

「API Design Patterns」の第10章「Long-running operations」は、APIにおける長時間実行操作の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者は長時間実行操作（LRO）が単なる機能の追加ではなく、APIの柔軟性、スケーラビリティ、そして長期的な運用性に直接影響を与える重要な設計上の決定であることを明確に示しています。

長時間実行操作の必要性と概要

著者は、APIにおける長時間実行操作の必要性から議論を始めています。多くのAPI呼び出しは数百ミリ秒以内に処理されますが、データ処理や外部サービスとの連携など、時間のかかる操作も存在します。これらの操作を同期的に処理すると、クライアントの待ち時間が長くなり、リソースの無駄遣いにつながる可能性があります。

長時間実行操作の概念は、プログラミング言語におけるPromiseやFutureと類似しています。APIの文脈では、これらの操作は「Long-running Operations」（LRO）と呼ばれ、非同期処理を可能にします。LROは、操作の進行状況を追跡し、最終的な結果を取得するためのメカニズムを提供します。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。複数のサービスが協調して動作する環境では、一つの操作が複数のサービスにまたがって実行される可能性があり、その全体の進行状況を追跡する必要があります。

著者は、LROの基本的な構造として以下の要素を提案しています。

一意の識別子
操作の状態（実行中、完了、エラーなど）
結果または発生したエラーの情報
進行状況や追加のメタデータ

これらの要素を含むLROは、APIリソースとして扱われ、クライアントはこのリソースを通じて操作の状態を確認し、結果を取得することができます。

LROの実装

LROの実装に関して、著者はいくつかの重要なポイントを強調しています。

リソースとしてのLRO: LROは通常のAPIリソースとして扱われ、一意の識別子を持ちます。これにより、クライアントは操作の状態を簡単に追跡できます。
ジェネリックな設計: LROインターフェースは、さまざまな種類の操作に対応できるように、結果の型とメタデータの型をパラメータ化します。
ステータス管理: 操作の状態（実行中、完了、エラーなど）を明確に表現する必要があります。
エラーハンドリング: 操作が失敗した場合のエラー情報を適切に提供する必要があります。
進行状況の追跡: 長時間実行操作の進行状況を追跡し、クライアントに提供するメカニズムが必要です。

これらの要素を考慮したLROの基本的な構造を、Rustを用いて表現すると以下のようになります。

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Operation {
    pub id: String,
    pub done: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub result: Option<serde_json::Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<ErrorInfo>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ErrorInfo {
    pub code: i32,
    pub message: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub details: Option<HashMap<String, serde_json::Value>>,
}

この構造により、APIは長時間実行操作の状態を効果的に表現し、クライアントに必要な情報を提供することができます。

LROの状態管理と結果の取得

著者は、LROの状態を管理し、結果を取得するための2つの主要なアプローチを提案しています。ポーリングと待機です。

ポーリング: クライアントが定期的にLROの状態を確認する方法です。これは実装が簡単ですが、不必要なAPI呼び出しが発生する可能性があります。
待機: クライアントがLROの完了を待つ長期接続を確立する方法です。これはリアルタイム性が高いですが、サーバー側のリソース管理が複雑になる可能性があります。

これらのアプローチを実装する際、著者は以下のAPIメソッドを提案しています。

GetOperation: LROの現在の状態を取得します。
ListOperations: 複数のLROをリストアップします。
WaitOperation: LROの完了を待機します。

これらのメソッドを適切に実装することで、クライアントは長時間実行操作の進行状況を効果的に追跡し、結果を取得することができます。

LROの制御と管理

著者は、LROをより柔軟に管理するための追加機能についても論じています。

キャンセル: 実行中の操作を中止する機能です。これは、不要になった操作やエラーが発生した操作を適切に終了させるために重要です。
一時停止と再開: 一部の操作では、一時的に処理を停止し、後で再開する機能が有用な場合があります。
有効期限: LROリソースをいつまで保持するかを決定するメカニズムです。これは、システムリソースの効率的な管理に役立ちます。

これらの機能を実装することで、APIの柔軟性と運用性が向上します。例えば、キャンセル機能は以下のように実装できます。

impl Service {
    pub async fn cancel_operation(&self, req: &CancelOperationRequest) -> Result<Operation, Error> {
        let mut op = self.get_operation(&GetOperationRequest { name: req.name.clone() }).await?;

        if op.done {
            return Ok(op);
        }

        // 操作をキャンセルするロジック
        // ...

        op.done = true;
        op.error = Some(ErrorInfo {
            code: StatusCode::CANCELLED as i32,
            message: "Operation cancelled by the user.".to_string(),
            details: None,
        });

        self.update_operation(&op).await
    }
}

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

スケーラビリティと性能: LROを適切に実装することで、APIのスケーラビリティと全体的な性能を向上させることができます。長時間実行操作を非同期で処理することで、サーバーリソースを効率的に利用し、クライアントの応答性を維持することができます。
信頼性とエラー処理: LROパターンは、長時間実行操作中に発生する可能性のあるエラーを適切に処理し、クライアントに伝達するメカニズムを提供します。これにより、システム全体の信頼性が向上します。
運用性と可観測性: LROリソースを通じて操作の進行状況や状態を追跡できることは、システムの運用性と可観測性を大幅に向上させます。これは、複雑な分散システムの問題診断や性能最適化に特に有用です。
ユーザーエクスペリエンス: クライアントに進行状況を提供し、長時間操作をキャンセルする機能を提供することで、APIのユーザーエクスペリエンスが向上します。
リソース管理: LROの有効期限を適切に設定することで、システムリソースを効率的に管理できます。これは、大規模なシステムの長期的な運用において特に重要です。

結論

第10章「Long-running operations」は、APIにおける長時間実行操作の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性、スケーラビリティ、そして長期的な運用性を大きく向上させる可能性があります。

LROを設計する際に考慮すべき点を列挙します。

LROは、長時間実行操作を非同期で処理するための強力なツールです。
LROをAPIリソースとして扱うことで、操作の状態管理と結果の取得が容易になります。
ポーリングと待機の両方のアプローチを提供することで、さまざまなクライアントのニーズに対応できます。
キャンセル、一時停止、再開などの制御機能を提供することで、APIの柔軟性が向上します。
LROリソースの適切な有効期限管理は、システムリソースの効率的な利用につながります。

同期APIで30秒タイムアウトを食らい続けたバッチ処理を、LROに書き換えたときの安堵感は忘れられない。「待たせる処理は待たせる設計にする」という当たり前を、タイムアウトエラーの山を見るまで学べなかった。非同期は逃げではなく、誠実な設計だ。

11 Rerunnable jobs

「API Design Patterns」の第11章「Rerunnable jobs」は、APIにおける再実行可能なジョブの概念、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者は再実行可能なジョブが単なる機能の追加ではなく、APIの柔軟性、スケーラビリティ、そして長期的な運用性に直接影響を与える重要な設計上の決定であることを明確に示しています。

Figure 11.1 Interaction with a Job resource より引用

再実行可能なジョブの必要性と概要

著者は、再実行可能なジョブの必要性から議論を始めています。多くのAPIでは、カスタマイズ可能で繰り返し実行する必要のある機能が存在します。しかし、従来のAPIデザインでは、これらの機能を効率的に管理することが困難でした。著者は、この問題に対処するために「ジョブ」という概念を導入しています。

ジョブは、APIメソッドの設定と実行を分離する特別なリソースとして定義されています。この分離には以下の利点があります。

設定の永続化：ジョブの設定をAPIサーバー側で保存できるため、クライアントは毎回詳細な設定を提供する必要がありません。
権限の分離：ジョブの設定と実行に異なる権限を設定できるため、セキュリティとアクセス制御が向上します。
スケジューリングの容易さ：ジョブをAPIサーバー側でスケジュールすることが可能になり、クライアント側での複雑なスケジューリング管理が不要になります。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、複数のサービスが協調して動作する環境では、定期的なデータ処理やバックアップなどの操作を効率的に管理する必要があります。再実行可能なジョブを使用することで、これらの操作を一貫した方法で設計し、実行することができます。この辺の再実行性について包括的に知りたいのであればデータ指向アプリケーションデザイン ―信頼性、拡張性、保守性の高い分散システム設計の原理がオススメです。

著者は、ジョブの基本的な構造として以下の要素を提案しています。

ジョブリソース：設定情報を保持するリソース
実行メソッド：ジョブを実行するためのカスタムメソッド
実行リソース：ジョブの実行結果を保持するリソース（必要な場合）

これらの要素を組み合わせることで、APIは柔軟で再利用可能なジョブ管理システムを提供することができます。

Figure 11.2 Interaction with a Job resource with Execution results より引用

ジョブリソースの実装

著者は、ジョブリソースの実装に関して詳細なガイダンスを提供しています。ジョブリソースは、通常のAPIリソースと同様に扱われますが、その目的は特定の操作の設定を保存することです。ジョブリソースの主な特徴は以下の通りです。

一意の識別子：他のリソースと同様に、ジョブリソースも一意の識別子を持ちます。
設定パラメータ：ジョブの実行に必要な全ての設定情報を保持します。
標準的なCRUD操作：ジョブリソースは作成、読み取り、更新、削除の標準的な操作をサポートします。

著者は、チャットルームのバックアップを例にとって、ジョブリソースの設計を説明しています。以下は、Rustを用いてこのジョブリソースを表現した例です。

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BackupChatRoomJob {
    pub id: String,
    pub chat_room_id: String,
    pub destination: String,
    pub compression_format: String,
    pub encryption_key: String,
}

このような設計により、ジョブの設定を永続化し、必要に応じて再利用することが可能になります。また、異なる権限レベルを持つユーザーがジョブの設定と実行を別々に管理できるようになります。

ジョブの実行とLRO

著者は、ジョブの実行方法についても詳細に説明しています。ジョブの実行は、カスタムメソッド（通常は「run」メソッド）を通じて行われます。このメソッドは、長時間実行操作（LRO）を返すことで、非同期実行をサポートします。

以下は、Rustを用いてジョブ実行メソッドを表現した例です。

impl Service {
    pub async fn run_backup_chat_room_job(
        &self,
        req: &RunBackupChatRoomJobRequest,
    ) -> Result<Operation, Error> {
        let job = self.get_backup_chat_room_job(&req.job_id).await?;

        let op = Operation {
            id: format!("operations/backup_{}", job.id),
            done: false,
            result: None,
            error: None,
            metadata: Some(serde_json::to_value(BackupChatRoomJobMetadata {
                job_id: job.id.clone(),
                status: "RUNNING".to_string(),
            })?),
        };

        // バックグラウンドでジョブを実行
        let job_clone = job.clone();
        let op_clone = op.clone();
        tokio::spawn(async move {
            Self::execute_backup_job(job_clone, op_clone).await;
        });

        Ok(op)
    }
}

このアプローチには以下の利点があります。

非同期実行：長時間かかる可能性のある操作を非同期で実行できます。
進捗追跡：LROを通じて、ジョブの進捗状況を追跡できます。
エラーハンドリング：LROを使用することで、ジョブ実行中のエラーを適切に処理し、クライアントに伝達できます。

実行リソースの導入

著者は、ジョブの実行結果を永続化するための「実行リソース」の概念を導入しています。これは、LROの有効期限が限定される可能性がある場合に特に重要です。実行リソースの主な特徴は以下の通りです。

読み取り専用：実行リソースは、ジョブの実行結果を表すため、通常は読み取り専用です。
ジョブとの関連付け：各実行リソースは、特定のジョブリソースに関連付けられます。
結果の永続化：ジョブの実行結果を長期的に保存し、後で参照することができます。

以下は、Rustを用いて実行リソースを表現した例です。

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AnalyzeChatRoomJobExecution {
    pub id: String,
    pub job_id: String,
    pub execution_time: DateTime<Utc>,
    pub sentence_complexity: f64,
    pub sentiment: f64,
    pub abuse_score: f64,
}

実行リソースを導入することで、ジョブの実行履歴を管理し、結果を長期的に保存することが可能になります。これは、データ分析や監査の目的で特に有用です。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

スケーラビリティと性能: 再実行可能なジョブを適切に実装することで、APIのスケーラビリティと全体的な性能を向上させることができます。長時間実行される操作を非同期で処理することで、サーバーリソースを効率的に利用し、クライアントの応答性を維持することができます。
運用性と可観測性: ジョブリソースと実行リソースを導入することで、システムの運用性と可観測性が向上します。ジョブの設定、実行状況、結果を一元的に管理できるため、問題の診断や性能最適化が容易になります。
セキュリティとアクセス制御: ジョブの設定と実行を分離することで、より細かいアクセス制御が可能になります。これは、大規模な組織や複雑なシステムにおいて特に重要です。
バージョニングと後方互換性: ジョブリソースを使用することで、APIの進化に伴う変更を管理しやすくなります。新しいパラメータや機能を追加する際も、既存のジョブとの互換性を維持しやすくなります。
スケジューリングと自動化: 再実行可能なジョブは、定期的なタスクやバッチ処理の自動化に適しています。これは、データ処理パイプラインやレポート生成などのシナリオで特に有用です。

結論

第11章「Rerunnable jobs」は、APIにおける再実行可能なジョブの重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性、スケーラビリティ、そして長期的な運用性を大きく向上させる可能性があります。

この章で学んだ設計の勘所を4つにまとめます。

ジョブリソースを導入することで、設定と実行を分離し、再利用性を高めることができます。
カスタムの実行メソッドとLROを組み合わせることで、非同期実行と進捗追跡を実現できます。
実行リソースを使用することで、ジョブの結果を永続化し、長期的な分析や監査を可能にします。
この設計パターンは、セキュリティ、スケーラビリティ、運用性の向上に貢献します。

「実行」と「設定」を分離せずに作ったバッチAPIは、毎回同じパラメータを渡す羽目になった。ジョブリソースを導入してからは「設定を保存して、実行は1クリック」になり、オペレーションミスが激減した。設定と実行の分離は、人間のエラーを減らす設計だ。

Part 4 Resource relationships

リソース間の関係性を設計した。レビューを通した。本番にデプロイした。3ヶ月後、「このリソースって誰の所有物？」という質問がSlackに流れた。答えられなかった。ドキュメントを見た。書いていなかった。書いたつもりだった。書いていなかった。

ここでは、APIにおけるリソース間の関係性の表現方法について詳しく解説されています。シングルトンサブリソース、クロスリファレンス、関連リソース、ポリモーフィズムなど、複雑なデータ構造や関係性を APIで表現するための高度なテクニックが紹介されています。これらのパターンを理解し適切に適用することで、より柔軟で表現力豊かなAPIを設計することができます。

12 Singleton sub-resources

「API Design Patterns」の第12章「Singleton sub-resources」は、APIにおけるシングルトンサブリソースの概念、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はシングルトンサブリソースが単なる設計上の選択ではなく、APIの柔軟性、スケーラビリティ、そして長期的な保守性に直接影響を与える重要な設計パターンであることを明確に示しています。

シングルトンサブリソースの必要性と概要

著者は、シングルトンサブリソースの必要性から議論を始めています。多くのAPIでは、リソースの一部のデータを独立して管理する必要が生じることがあります。例えば、アクセス制御リスト（ACL）のような大規模なデータ、頻繁に更新される位置情報、または特別なセキュリティ要件を持つデータなどが該当します。これらのデータを主リソースから分離することで、APIの効率性と柔軟性を向上させることができます。

シングルトンサブリソースは、リソースのプロパティとサブリソースの中間的な存在として定義されています。著者は、この概念を以下のように説明しています。

親リソースに従属：シングルトンサブリソースは常に親リソースに関連付けられます。
単一インスタンス：各親リソースに対して、特定のタイプのシングルトンサブリソースは1つしか存在しません。
独立した管理：シングルトンサブリソースは、親リソースとは別に取得や更新が可能です。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、ユーザーサービスと位置情報サービスを分離しつつ、両者の関連性を維持したい場合に、シングルトンサブリソースが有効です。

シングルトンサブリソースの実装

著者は、シングルトンサブリソースの実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

標準メソッドの制限: シングルトンサブリソースは、通常のリソースとは異なり、標準のCRUD操作の一部のみをサポートします。具体的には、Get（取得）とUpdate（更新）のみが許可されます。
暗黙的な作成と削除: シングルトンサブリソースは親リソースの作成時に自動的に作成され、親リソースの削除時に自動的に削除されます。
リセット機能: 著者は、シングルトンサブリソースを初期状態にリセットするためのカスタムメソッドの実装を推奨しています。
階層構造: シングルトンサブリソースは常に親リソースの直下に位置し、他のシングルトンサブリソースの子になることはありません。

これらの原則を適用することで、APIの一貫性と予測可能性を維持しつつ、特定のデータを効率的に管理することができます。

以下は、Rustを用いてシングルトンサブリソースを実装する例です。

use async_trait::async_trait;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Driver {
    pub id: String,
    pub name: String,
    pub license_plate: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DriverLocation {
    pub id: String,
    pub driver_id: String,
    pub latitude: f64,
    pub longitude: f64,
    pub updated_at: DateTime<Utc>,
}

#[async_trait]
pub trait DriverService {
    async fn get_driver(&self, id: &str) -> Result<Driver, Error>;
    async fn update_driver(&self, driver: &Driver) -> Result<(), Error>;
    async fn get_driver_location(&self, driver_id: &str) -> Result<DriverLocation, Error>;
    async fn update_driver_location(&self, location: &DriverLocation) -> Result<(), Error>;
    async fn reset_driver_location(&self, driver_id: &str) -> Result<(), Error>;
}

この例では、DriverリソースとDriverLocationシングルトンサブリソースを定義しています。DriverServiceトレイトは、これらのリソースに対する操作を定義しています。

シングルトンサブリソースの利点と課題

著者は、シングルトンサブリソースの利点と課題について詳細に論じています。

利点:

データの分離: 頻繁に更新されるデータや大量のデータを分離することで、主リソースの管理が容易になります。
細粒度のアクセス制御: 特定のデータに対して、より詳細なアクセス制御を実装できます。
パフォーマンスの向上: 必要なデータのみを取得・更新することで、APIのパフォーマンスが向上します。

課題:

原子性の欠如: 親リソースとサブリソースを同時に更新することができないため、データの一貫性を維持するための追加の作業が必要になる場合があります。
複雑性の増加: APIの構造が若干複雑になり、クライアント側の実装が少し難しくなる可能性があります。

これらの利点と課題を考慮しながら、シングルトンサブリソースの適用を検討する必要があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

スケーラビリティと性能: シングルトンサブリソースを適切に実装することで、APIのスケーラビリティと全体的な性能を向上させることができます。特に、大規模なデータや頻繁に更新されるデータを扱う場合に有効です。
セキュリティとアクセス制御: シングルトンサブリソースを使用することで、特定のデータに対してより細かいアクセス制御を実装できます。これは、セキュリティ要件が厳しい環境で特に重要です。
システムの進化: シングルトンサブリソースパターンを採用することで、システムの将来的な拡張や変更が容易になります。新しい要件が発生した際に、既存のリソース構造を大きく変更することなく、新しいサブリソースを追加できます。
マイクロサービスアーキテクチャとの親和性: シングルトンサブリソースの概念は、マイクロサービスアーキテクチャにおいてサービス間の境界を定義する際に特に有用です。例えば、ユーザープロファイルサービスと位置情報サービスを分離しつつ、両者の関連性を維持することができます。
運用性と可観測性: シングルトンサブリソースを使用することで、特定のデータの変更履歴や更新頻度を独立して追跡しやすくなります。これにより、システムの運用性と可観測性が向上します。

結論

第12章「Singleton sub-resources」は、APIにおけるシングルトンサブリソースの重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性、スケーラビリティ、そして長期的な保守性を大きく向上させる可能性があります。

シングルトンサブリソースを採用する判断軸は4つです。

シングルトンサブリソースは、特定のデータを親リソースから分離しつつ、強い関連性を維持する効果的な方法です。
Get（取得）とUpdate（更新）のみをサポートし、作成と削除は親リソースに依存します。
シングルトンサブリソースは、大規模データ、頻繁に更新されるデータ、特別なセキュリティ要件を持つデータの管理に特に有効です。
このパターンを採用する際は、データの一貫性維持やAPI複雑性の増加といった課題にも注意を払う必要があります。

ユーザー設定を親リソースに全部埋め込んでいたら、設定だけ更新したいのに毎回ユーザー全体をPUTする羽目になった。/users/{id}/settings に分離したら、権限管理もキャッシュ戦略も楽になった。「1リソース1責務」はAPIでも生きている。

13 Cross references

「API Design Patterns」の第13章「Cross references」は、APIにおけるリソース間の参照の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はリソース間の参照が単なる技術的な実装の詳細ではなく、APIの柔軟性、一貫性、そして長期的な保守性に直接影響を与える重要な設計上の決定であることを明確に示しています。

リソース間参照の必要性と概要

著者は、リソース間参照の必要性から議論を始めています。多くのAPIでは、複数のリソースタイプが存在し、これらのリソース間に関連性がある場合が多々あります。例えば、書籍リソースと著者リソースの関係などが挙げられます。これらの関連性を適切に表現し、管理することが、APIの使いやすさと柔軟性を向上させる上で重要です。

著者は、リソース間参照の範囲について、以下のように分類しています。

ローカル参照：同じAPI内の他のリソースへの参照
グローバル参照：インターネット上の他のリソースへの参照
中間的参照：同じプロバイダーが提供する異なるAPI内のリソースへの参照

この概念を視覚的に表現するために、著者は以下の図を提示しています。

Figure 13.1 Resources can point at others in the same API or in external APIs. より引用

この図は、リソースが同じAPI内の他のリソース、外部APIのリソース、そしてインターネット上の任意のリソースを参照できることを示しています。これは、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、ユーザーサービス、注文サービス、支払いサービスなど、複数のマイクロサービス間でリソースを相互参照する必要がある場合に、この概念が適用されます。

著者は、リソース間参照の基本的な実装として、文字列型の一意識別子を使用することを提案しています。これにより、同じAPI内のリソース、異なるAPIのリソース、さらにはインターネット上の任意のリソースを統一的に参照することが可能になります。

リソース間参照の実装

著者は、リソース間参照の実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

参照フィールドの命名: 著者は、参照フィールドの名前に「Id」サフィックスを付けることを推奨しています。例えば、BookリソースがAuthorリソースを参照する場合、参照フィールドはauthorIdと命名します。これにより、フィールドの目的が明確になり、APIの一貫性が向上します。
動的リソースタイプの参照: 参照先のリソースタイプが動的に変化する場合、著者は追加のtypeフィールドを使用することを提案しています。これにより、異なるタイプのリソースを柔軟に参照できます。
データ整合性: 著者は、参照の整合性（つまり、参照先のリソースが常に存在することを保証すること）を維持することの難しさを指摘しています。代わりに、APIクライアントが参照の有効性を確認する責任を負うアプローチを提案しています。
値vs参照: 著者は、参照先のリソースデータをコピーして保持するか（値渡し）、単に参照を保持するか（参照渡し）のトレードオフについて議論しています。一般的に、参照を使用することを推奨していますが、特定の状況では値のコピーが適切な場合もあることを認めています。

これらの原則を適用した、Rustでのリソース間参照の実装例を以下に示します。

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Book {
    pub id: String,
    pub title: String,
    pub author_id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Author {
    pub id: String,
    pub name: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ChangeLogEntry {
    pub id: String,
    pub target_id: String,
    pub target_type: String,
    pub description: String,
}

この実装では、Book構造体がauthor_idフィールドを通じてAuthor構造体を参照しています。また、ChangeLogEntry構造体は動的なリソースタイプを参照できるよう設計されています。

リソース間参照の利点と課題

著者は、リソース間参照の利点と課題について詳細に論じています。

利点:

柔軟性: リソース間の関係を柔軟に表現できます。
一貫性: 参照の表現方法が統一され、APIの一貫性が向上します。
スケーラビリティ: 大規模なシステムでも、リソース間の関係を効率的に管理できます。

課題:

データ整合性: 参照先のリソースが削除された場合、無効な参照（dangling reference）が発生する可能性があります。
パフォーマンス: 関連するデータを取得するために複数のAPI呼び出しが必要になる場合があります。
複雑性: 動的リソースタイプの参照など、一部の実装は複雑になる可能性があります。

これらの利点と課題を考慮しながら、リソース間参照の適用を検討する必要があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの親和性: リソース間参照の概念は、マイクロサービス間でのデータの関連付けに直接適用できます。例えば、注文サービスがユーザーサービスのユーザーIDを参照する際に、この設計パターンを使用できます。
スケーラビリティとパフォーマンス: 参照を使用することで、各リソースを独立して管理できるため、システムのスケーラビリティが向上します。ただし、関連データの取得に複数のAPI呼び出しが必要になる可能性があるため、パフォーマンスとのバランスを取る必要があります。
データ整合性と可用性のトレードオフ: 強力なデータ整合性を維持しようとすると（例：参照先のリソースの削除を禁止する）、システムの可用性が低下する可能性があります。著者の提案する「緩やかな参照」アプローチは、高可用性を維持しつつ、整合性の問題をクライアント側で処理する責任を負わせます。
APIの進化と後方互換性: リソース間参照を適切に設計することで、APIの進化が容易になります。新しいリソースタイプの追加や、既存のリソース構造の変更が、既存の参照に影響を与えにくくなります。
監視と運用: リソース間参照を使用する場合、無効な参照の発生を監視し、必要に応じて修正するプロセスを確立することが重要です。これは、システムの長期的な健全性を維持する上で重要な運用タスクとなります。

結論

第13章「Cross references」は、APIにおけるリソース間参照の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性、一貫性、そして長期的な保守性を大きく向上させる可能性があります。

リソース間参照の設計で守るべきルールを挙げます。

リソース間参照は、単純な文字列型の識別子を使用して実装すべきです。
参照フィールドの命名には一貫性が重要で、「Id」サフィックスの使用が推奨されます。
データ整合性の維持は難しいため、クライアント側で参照の有効性を確認する責任を持たせるアプローチが推奨されます。
値のコピーよりも参照の使用が一般的に推奨されますが、特定の状況では値のコピーが適切な場合もあります。
GraphQLなどの技術を活用することで、リソース間参照に関連するパフォーマンスの問題を軽減できる可能性があります。

IDだけ返すか、関連リソースを埋め込むか。この判断を間違えると、N+1クエリか過剰なペイロードか、どちらかの地獄が待っている。私は「デフォルトはIDのみ、expand パラメータで展開」に落ち着いた。正解はないが、一貫性はある。

14 Association resources

「API Design Patterns」の第14章「Association resources」は、多対多の関係を持つリソース間の関連性を扱うAPI デザインパターンについて詳細に解説しています。この章を通じて、著者は関連リソースの概念、その実装方法、そしてトレードオフについて明確に示し、APIの柔軟性、スケーラビリティ、そして長期的な保守性にどのように影響するかを説明しています。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの親和性: 関連リソースのパターンは、マイクロサービス間のデータの関連付けに直接適用できます。例えば、ユーザーサービスとグループサービスの間の関係を管理する独立したサービスとして実装することができます。
スケーラビリティとパフォーマンス: 関連リソースを独立して管理することで、システムのスケーラビリティが向上します。ただし、関連データの取得に追加のAPI呼び出しが必要になる可能性があるため、パフォーマンスとのバランスを取る必要があります。このトレードオフを管理するために、キャッシング戦略やバッチ処理の導入を検討する必要があるでしょう。
データ整合性と可用性のトレードオフ: 参照整合性を厳密に維持しようとすると、システムの可用性が低下する可能性があります。一方で、緩やかな整合性を許容すると、無効な関連が一時的に存在する可能性があります。このトレードオフを適切に管理するために、非同期の整合性チェックやイベント駆動型のアーキテクチャの導入を検討することができます。
APIの進化と後方互換性: 関連リソースパターンを採用することで、APIの進化が容易になります。新しいタイプの関連や追加のメタデータを導入する際に、既存のクライアントに影響を与えることなく拡張できます。
監視と運用: 関連リソースを使用する場合、無効な関連の発生を監視し、必要に応じて修正するプロセスを確立することが重要です。また、関連リソースの数が増加した場合のパフォーマンスの影響や、ストレージの使用量なども監視する必要があります。
セキュリティとアクセス制御: 関連リソースに対するアクセス制御を適切に設計することが重要です。例えば、ユーザーがグループのメンバーシップを表示したり変更したりする権限を、きめ細かく制御する必要があります。
クエリの最適化: 関連リソースを効率的に取得するためのクエリパラメータやフィルタリングオプションを提供することが重要です。例えば、特定のユーザーが所属するすべてのグループを一度に取得するような最適化されたエンドポイントを提供することを検討できます。
バルク操作のサポート: 大量の関連を一度に作成、更新、削除する必要がある場合、バルク操作をサポートすることで効率性を向上させることができます。
イベント駆動設計との統合: 関連リソースの変更（作成、更新、削除）をイベントとして発行することで、他のサービスやシステムコンポーネントが適切に反応し、全体的な整合性を維持することができます。
ドキュメンテーションと開発者エクスペリエンス: 関連リソースの概念と使用方法を明確にドキュメント化し、開発者がこのパターンを効果的に利用できるようにすることが重要です。API利用者が関連リソースを簡単に作成、管理、クエリできるようなツールやSDKを提供することも検討すべきです。

結論

第14章「Association resources」は、多対多の関係を持つリソース間の関連性を管理するための重要なパターンを提供しています。このパターンは、APIの柔軟性、スケーラビリティ、そして長期的な保守性を大きく向上させる可能性があります。

関連リソースを導入する際のチェックリストです。

関連リソースは、多対多の関係を独立したエンティティとして扱うことで、複雑な関係の管理を容易にします。
標準的なCRUD操作をサポートし、関連性に関する追加のメタデータを管理できるようにすることが重要です。
一意性制約と参照整合性の維持は、関連リソースの設計において重要な考慮事項です。
このパターンは柔軟性と拡張性を提供しますが、APIの複雑性とパフォーマンスへの影響を慎重に検討する必要があります。
マイクロサービスアーキテクチャやクラウドネイティブ環境において、このパターンは特に有用です。

ユーザーとロールの多対多関係を、最初は中間テーブルなしで埋め込んでいた。権限の監査ログを取りたくなったとき、関連リソースに分離するのに丸1週間かかった。「後から分離できる」は幻想だ。関係にメタデータが付く可能性があるなら、最初から分離する。

15 Add and remove custom methods

「API Design Patterns」の第15章「Add and remove custom methods」は、多対多の関係を持つリソース間の関連性を管理するための代替パターンについて詳細に解説しています。この章を通じて、著者はカスタムのaddおよびremoveメソッドを使用して、関連リソースを導入せずに多対多の関係を管理する方法とそのトレードオフについて明確に示しています。

動機と概要

著者は、前章で紹介した関連リソースパターンが柔軟性が高い一方で、複雑さも増すことを指摘しています。そこで、より単純なアプローチとして、カスタムのaddおよびremoveメソッドを使用する方法を提案しています。このパターンは、関係性に関するメタデータを保存する必要がない場合や、APIの複雑さを抑えたい場合に特に有効です。

このアプローチの核心は、リソース間の関係性を管理するための専用のリソース（関連リソース）を作成せず、代わりに既存のリソースに対してaddとremoveの操作を行うことです。例えば、ユーザーとグループの関係を管理する場合、AddGroupUserやRemoveGroupUserといったメソッドを使用します。

この設計パターンは、マイクロサービスアーキテクチャにおいて特に興味深い応用が考えられます。例えば、ユーザー管理サービスとグループ管理サービスが分離されている環境で、これらのサービス間の関係性を簡潔に管理する方法として活用できます。このパターンを採用することで、サービス間の結合度を低く保ちつつ、必要な関係性を効率的に管理することが可能になります。

著者は、このパターンの主な制限事項として以下の2点を挙げています。

関係性に関するメタデータを保存できない
リソース間の関係性に方向性が生まれる（管理するリソースと管理されるリソースが明確に分かれる）

これらの制限は、システムの設計と実装に大きな影響を与える可能性があるため、慎重に検討する必要があります。

実装の詳細

著者は、addおよびremoveカスタムメソッドの実装について詳細なガイダンスを提供しています。主なポイントは以下の通りです。

メソッド名の規則: Add<Managing-Resource><Associated-Resource>およびRemove<Managing-Resource><Associated-Resource>の形式を使用します。例えば、AddGroupUserやRemoveGroupUserといった具合です。
リクエストの構造: これらのメソッドは、管理するリソース（親リソース）と関連付けるリソースのIDを含むリクエストを受け取ります。
関連リソースの一覧取得: 関連付けられたリソースの一覧を取得するために、カスタムのリストメソッドを提供します。例えば、ListGroupUsersやListUserGroupsといったメソッドです。
データの整合性: 重複した関連付けや存在しない関連の削除といった操作に対して、適切なエラーハンドリングを実装する必要があります。

これらの原則を適用した実装例を、Rustを用いて示すと以下のようになります。

use async_trait::async_trait;

#[async_trait]
pub trait GroupService {
    async fn add_group_user(&self, group_id: &str, user_id: &str) -> Result<(), Error>;
    async fn remove_group_user(&self, group_id: &str, user_id: &str) -> Result<(), Error>;
    async fn list_group_users(&self, group_id: &str, page_token: &str, page_size: i32) -> Result<(Vec<User>, String), Error>;
    async fn list_user_groups(&self, user_id: &str, page_token: &str, page_size: i32) -> Result<(Vec<Group>, String), Error>;
}

impl GroupService for GroupServiceImpl {
    async fn add_group_user(&self, group_id: &str, user_id: &str) -> Result<(), Error> {
        // 実装の詳細...
        // 重複チェック、存在チェック、データベース操作など
        Ok(())
    }

    async fn remove_group_user(&self, group_id: &str, user_id: &str) -> Result<(), Error> {
        // 実装の詳細...
        // 存在チェック、データベース操作など
        Ok(())
    }

    async fn list_group_users(&self, group_id: &str, page_token: &str, page_size: i32) -> Result<(Vec<User>, String), Error> {
        // 実装の詳細...
        // ページネーション処理、データベースクエリなど
        let users = vec![];
        let next_page_token = String::new();
        Ok((users, next_page_token))
    }
}

この実装例では、GroupServiceトレイトがaddとremoveのカスタムメソッド、および関連リソースの一覧を取得するためのメソッドを定義しています。これらのメソッドは、グループとユーザー間の関係性を管理するための基本的な操作を提供します。

利点と課題

著者は、このパターンの主な利点と課題について詳細に論じています。

利点:

シンプルさ: 関連リソースを導入せずに多対多の関係を管理できるため、APIの構造がシンプルになります。
実装の容易さ: 既存のリソースに対するカスタムメソッドとして実装できるため、新しいリソースタイプを導入する必要がありません。
パフォーマンス: 関連リソースを介さずに直接操作できるため、特定のシナリオではパフォーマンスが向上する可能性があります。

課題:

メタデータの制限: 関係性に関する追加のメタデータ（例：関連付けられた日時、関連の種類など）を保存できません。
方向性の制約: リソース間の関係に明確な方向性が生まれるため、一部のユースケースでは直感的でない設計になる可能性があります。
柔軟性の低下: 関連リソースパターンと比較して、関係性の表現や操作の柔軟性が低下します。

これらの利点と課題を考慮しながら、システムの要件に応じてこのパターンの適用を検討する必要があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

スケーラビリティとパフォーマンス: addとremoveカスタムメソッドを使用することで、特定のシナリオではシステムのスケーラビリティとパフォーマンスが向上する可能性があります。例えば、大規模なソーシャルネットワークアプリケーションで、ユーザー間のフォロー関係を管理する場合、このパターンを使用することで、関連リソースを介さずに直接的かつ効率的に関係性を操作できます。
運用の簡素化: このパターンを採用することで、関連リソースの管理が不要になるため、システムの運用が簡素化される可能性があります。例えば、データベースのスキーマがシンプルになり、マイグレーションやバックアップの複雑さが軽減されます。
マイクロサービスアーキテクチャとの親和性: このパターンは、マイクロサービス間の関係性を管理する際に特に有用です。例えば、ユーザーサービスとコンテンツサービスが分離されている環境で、ユーザーがコンテンツに「いいね」をつける機能を実装する場合、このパターンを使用することで、サービス間の結合度を低く保ちつつ、必要な関係性を効率的に管理することができます。
API進化の容易さ: 関連リソースを導入せずに関係性を管理できるため、APIの進化が容易になる可能性があります。新しい種類の関係性を追加する際に、既存のリソースに新しいカスタムメソッドを追加するだけで対応できます。
監視と可観測性: addとremoveの操作が明示的なメソッドとして定義されているため、これらの操作の頻度や性能を直接的に監視しやすくなります。これにより、システムの挙動をより細かく把握し、最適化の機会を見出すことができます。
セキュリティとアクセス制御: カスタムメソッドを使用することで、関係性の操作に対する細かなアクセス制御を実装しやすくなります。例えば、特定のユーザーグループのみがグループにメンバーを追加できるようにするといった制御が容易になります。
バッチ処理とバルク操作: このパターンは、大量の関係性を一度に操作する必要がある場合にも適しています。例えば、AddGroupUsersやRemoveGroupUsersといったバルク操作用のメソッドを追加することで、効率的な処理が可能になります。
イベント駆動アーキテクチャとの統合: addやremove操作をイベントとして発行することで、システム全体の反応性と柔軟性を向上させることができます。例えば、ユーザーがグループに追加されたときに、通知サービスや権限管理サービスにイベントを発行し、適切なアクションを起こすことができます。

結論

第15章「Add and remove custom methods」は、多対多の関係を管理するための代替パターンとして、カスタムのaddおよびremoveメソッドの使用を提案しています。このパターンは、APIの複雑さを抑えつつ、効率的に関係性を管理したい場合に特に有効です。

このパターンを選ぶ理由と制約を整理します。

このパターンは、関連リソースを導入せずに多対多の関係を管理できるため、APIの構造をシンプルに保つことができます。
addとremoveのカスタムメソッドを使用することで、関係性の操作が明示的かつ直感的になります。
関係性に関するメタデータを保存できないという制限があるため、適用する前にユースケースを慎重に検討する必要があります。
このパターンは、マイクロサービスアーキテクチャやイベント駆動アーキテクチャとの親和性が高く、効率的なシステム設計を可能にします。
運用の簡素化、監視の容易さ、セキュリティ制御の柔軟性など、システム全体の管理性向上にも貢献します。

このパターンを正しく使えば、APIの複雑さを抑えつつ効率的な関係管理が実現できます。現代の分散システムでも有効なアプローチです。

ただし、このパターンの採用を検討する際は、システムの要件と制約を慎重に評価する必要があります。関係性に関するメタデータが重要である場合や、リソース間の関係に明確な方向性を持たせたくない場合は、前章で紹介された関連リソースパターンの方が適している可能性があります。

最後に、API設計はシステム全体のアーキテクチャと密接に関連しています。addとremoveカスタムメソッドのパターンを採用する際は、単にAPIの使いやすさを向上させるだけでなく、システム全体の柔軟性、スケーラビリティ、そして運用効率の向上にどのように貢献するかを常に考慮する必要があります。適切に実装されたこのパターンは、システムの進化と拡張を容易にし、長期的な保守性を向上させる強力なツールとなります。

API設計者とシステム設計者は、このパターンの利点と制限を十分に理解し、プロジェクトの要件に応じて適切に適用することで、より堅牢で柔軟性の高いシステムを構築することができるでしょう。特に、マイクロサービスアーキテクチャやクラウドネイティブ環境において、このパターンは複雑な関係性を効率的に管理するための強力な選択肢となり得ます。

16 Polymorphism

「API Design Patterns」の第16章「Polymorphism」は、APIにおけるポリモーフィズムの概念、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はオブジェクト指向プログラミングの強力な概念であるポリモーフィズムをAPIデザインに適用する方法と、それがAPIの柔軟性、保守性、そして長期的な進化可能性にどのように影響を与えるかを明確に示しています。

ポリモーフィズムの必要性と概要

著者は、オブジェクト指向プログラミング（OOP）におけるポリモーフィズムの概念から議論を始めています。ポリモーフィズムは、異なる具体的な型に対して共通のインターフェースを使用する能力を提供し、特定の型と対話する際に理解する必要がある実装の詳細を最小限に抑えます。著者は、この強力な概念をオブジェクト指向プログラミングの世界からリソース指向のAPIデザインの世界に翻訳する方法を探求しています。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、メッセージングサービスを考えてみましょう。テキストメッセージ、画像メッセージ、音声メッセージなど、様々な種類のメッセージが存在する可能性があります。これらのメッセージタイプは共通の特性（送信者、タイムスタンプなど）を持ちながら、それぞれ固有の属性（テキスト内容、画像URL、音声ファイルの長さなど）も持っています。

ポリモーフィックリソースを使用することで、これらの異なるメッセージタイプを単一のMessageリソースとして扱い、共通の操作（作成、取得、一覧表示など）を提供しつつ、各タイプに固有の属性や振る舞いを維持することができます。これにより、APIの一貫性が向上し、クライアントの実装が簡素化されます。

著者は、ポリモーフィックリソースの基本的な構造として以下の要素を提案しています。

一意の識別子
リソースのタイプを示す明示的なフィールド
共通の属性
タイプ固有の属性

これらの要素を組み合わせることで、APIは柔軟で拡張可能なリソース表現を提供することができます。

ポリモーフィックリソースの実装

著者は、ポリモーフィックリソースの実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

タイプフィールドの定義: リソースのタイプを示すフィールドは、単純な文字列として実装することが推奨されています。これにより、新しいタイプの追加が容易になります。
データ構造: ポリモーフィックリソースは、すべてのサブタイプの属性をカバーするスーパーセットとして設計されます。これにより、各タイプに固有の属性を柔軟に扱うことができます。
バリデーション: タイプに応じて異なるバリデーションルールを適用する必要があります。例えば、テキストメッセージと画像メッセージでは、contentフィールドの有効な値が異なります。
標準メソッドの実装: ポリモーフィックリソースに対する標準的なCRUD操作は、通常のリソースと同様に実装されますが、タイプに応じて異なる振る舞いを持つ可能性があります。

これらの原則を適用した、Rustでのポリモーフィックリソースの実装例を以下に示します。

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use thiserror::Error;

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum MessageType {
    Text,
    Image,
    Audio,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Message {
    pub id: String,
    #[serde(rename = "type")]
    pub message_type: MessageType,
    pub sender: String,
    pub timestamp: DateTime<Utc>,
    pub content: MessageContent,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum MessageContent {
    Text(TextContent),
    Image(ImageContent),
    Audio(AudioContent),
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TextContent {
    pub text: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ImageContent {
    pub url: String,
    pub width: i32,
    pub height: i32,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AudioContent {
    pub url: String,
    pub duration: f64,
}

#[derive(Error, Debug)]
pub enum ValidationError {
    #[error("invalid content for {0} message")]
    InvalidContent(String),
    #[error("unknown message type")]
    UnknownType,
}

impl Message {
    pub fn validate(&self) -> Result<(), ValidationError> {
        match (&self.message_type, &self.content) {
            (MessageType::Text, MessageContent::Text(_)) => Ok(()),
            (MessageType::Image, MessageContent::Image(_)) => Ok(()),
            (MessageType::Audio, MessageContent::Audio(_)) => Ok(()),
            (MessageType::Text, _) => Err(ValidationError::InvalidContent("text".to_string())),
            (MessageType::Image, _) => Err(ValidationError::InvalidContent("image".to_string())),
            (MessageType::Audio, _) => Err(ValidationError::InvalidContent("audio".to_string())),
        }
    }
}

この実装例では、Message構造体がポリモーフィックリソースを表現し、contentフィールドがMessageContent enumを使用することで、異なるタイプのコンテンツを柔軟に扱えるようになっています。validateメソッドは、メッセージタイプに応じて適切なバリデーションを行います。

ポリモーフィズムの利点と課題

著者は、APIにおけるポリモーフィズムの利点と課題について詳細に論じています。

利点:

柔軟性: 新しいリソースタイプを追加する際に、既存のAPIメソッドを変更する必要がありません。
一貫性: 共通の操作を単一のインターフェースで提供することで、APIの一貫性が向上します。
クライアントの簡素化: クライアントは、異なるタイプのリソースを統一的に扱うことができます。

課題:

複雑性の増加: ポリモーフィックリソースの設計と実装は、単一タイプのリソースよりも複雑になる可能性があります。
パフォーマンス: タイプに応じた処理が必要なため、一部のケースでパフォーマンスが低下する可能性があります。
バージョニングの難しさ: 新しいタイプの追加や既存タイプの変更が、既存のクライアントに影響を与える可能性があります。

これらの利点と課題を考慮しながら、ポリモーフィズムの適用を検討する必要があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの親和性: ポリモーフィックリソースは、マイクロサービス間でのデータの一貫した表現に役立ちます。例えば、通知サービスが様々な種類の通知（メール、プッシュ通知、SMSなど）を統一的に扱う場合に有用です。
スケーラビリティとパフォーマンス: ポリモーフィックリソースを適切に設計することで、新しいリソースタイプの追加が容易になり、システムの拡張性が向上します。ただし、タイプチェックやバリデーションのオーバーヘッドに注意が必要です。
運用の簡素化: 共通のインターフェースを使用することで、監視、ログ記録、デバッグなどの運用タスクが簡素化される可能性があります。例えば、すべてのメッセージタイプに対して統一的なログフォーマットを使用できます。
APIの進化と後方互換性: ポリモーフィックリソースを使用することで、新しいリソースタイプの追加が容易になります。ただし、既存のタイプを変更する際は、後方互換性に十分注意を払う必要があります。
ドキュメンテーションと開発者エクスペリエンス: ポリモーフィックリソースの概念と使用方法を明確にドキュメント化し、開発者がこのパターンを効果的に利用できるようにすることが重要です。
バリデーションとエラーハンドリング: タイプに応じた適切なバリデーションを実装し、エラーメッセージを明確に定義することが重要です。これにより、APIの信頼性と使いやすさが向上します。
キャッシング戦略: ポリモーフィックリソースのキャッシングは複雑になる可能性があります。タイプに応じて異なるキャッシュ戦略を適用することを検討する必要があります。
セキュリティとアクセス制御: 異なるタイプのリソースに対して、適切なアクセス制御を実装することが重要です。例えば、特定のユーザーが特定のタイプのメッセージのみを作成できるようにする場合などです。

ポリモーフィックメソッドの回避

著者は、ポリモーフィックリソースの使用を推奨する一方で、ポリモーフィックメソッド（複数の異なるリソースタイプで動作する単一のAPIメソッド）の使用を強く警告しています。これは非常に重要な指摘です。

ポリモーフィックメソッドは、一見すると便利に見えますが、長期的には多くの問題を引き起こす可能性があります。

柔軟性の欠如: 異なるリソースタイプが将来的に異なる振る舞いを必要とする可能性があります。ポリモーフィックメソッドはこの柔軟性を制限します。
複雑性の増加: メソッド内で多くの条件分岐が必要になり、コードの複雑性が増加します。
バージョニングの難しさ: 一部のリソースタイプに対してのみ変更を加えたい場合、既存のクライアントに影響を与えずにそれを行うことが困難になります。
ドキュメンテーションの複雑さ: 様々なリソースタイプに対する振る舞いを明確にドキュメント化することが難しくなります。

代わりに、著者は各リソースタイプに対して個別のメソッドを定義することを推奨しています。これにより、APIの柔軟性と保守性が向上します。

結論

第16章「Polymorphism」は、APIにおけるポリモーフィズムの重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性、拡張性、そして長期的な保守性を大きく向上させる可能性があります。

ポリモーフィズムを導入する際の指針をまとめます。

ポリモーフィックリソースは、異なるサブタイプを持つリソースを効果的に表現し、管理するための強力なツールです。
タイプフィールドを使用してリソースのサブタイプを明示的に示すことで、APIの柔軟性と拡張性が向上します。
ポリモーフィックリソースの設計には慎重な考慮が必要で、特にデータ構造とバリデーションに注意を払う必要があります。
ポリモーフィックメソッドは避けるべきで、代わりに各リソースタイプに対して個別のメソッドを定義することが推奨されます。
ポリモーフィズムの適用は、APIの一貫性を向上させつつ、将来的な拡張性を確保するための効果的な手段となります。

「通知」をメール、SMS、プッシュで共通化しようとして、結局どれにも合わない中途半端な抽象ができたことがある。ポリモーフィズムは「共通化できる」ではなく「共通化すべきか」を問う必要がある。無理に統一すると、全員が不幸になる。

Part 5 Collective operations

一括操作を実装した。テストした。動いた。本番で動かした。10万件消えた。正確には、消えたのではなく、フィルタ条件のミスで意図しないリソースが対象になった。バックアップから戻した。3時間かかった。一括操作は便利だ。便利だが、怖い。

このパートでは、複数のリソースを一度に操作する方法について議論されています。コピーと移動、バッチ操作、条件付き削除、匿名書き込み、ページネーション、フィルタリング、インポートとエクスポートなど、大量のデータや複雑な操作を効率的に扱うための手法が紹介されています。これらの操作は、特に大規模なシステムやデータ集約型のアプリケーションにおいて重要です。

17 Copy and move

「API Design Patterns」の第17章「Copy and move」は、APIにおけるリソースのコピーと移動操作の実装方法、その複雑さ、そしてトレードオフについて詳細に論じています。この章を通じて、著者はこれらの操作が一見単純に見えるものの、実際には多くの考慮事項と課題を含む複雑な問題であることを明確に示しています。

コピーと移動操作の必要性と概要

著者は、理想的な世界ではリソースの階層関係が完璧に設計され、不変であるべきだと指摘しています。しかし現実には、ユーザーの誤りや要件の変更により、リソースの再配置や複製が必要になることがあります。この問題に対処するため、著者はカスタムメソッドを使用したコピーと移動操作の実装を提案しています。

これらの操作は、マイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、複数のサービス間でデータを移動したり、テスト環境から本番環境にリソースをコピーしたりする際に、これらの操作が必要になります。

著者は、コピーと移動操作の基本的な構造として以下の要素を提案しています。

カスタムメソッドの使用（標準のCRUD操作ではなく）
対象リソースの識別子
目的地（新しい親リソースまたは新しい識別子）

これらの要素を組み合わせることで、APIは柔軟かつ制御可能なコピーと移動操作を提供することができます。

実装の詳細と課題

著者は、コピーと移動操作の実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

識別子の扱い: コピー操作では、新しいリソースの識別子をどのように決定するか（ユーザー指定か、システム生成か）を慎重に検討する必要があります。移動操作では、識別子の変更が許可されるかどうかを考慮する必要があります。
子リソースの扱い: 親リソースをコピーまたは移動する際、子リソースをどのように扱うかを決定する必要があります。著者は、一般的に子リソースも一緒にコピーまたは移動すべきだと提案しています。
関連リソースの扱い: リソース間の参照関係をどのように維持するかを考慮する必要があります。特に移動操作では、関連リソースの参照を更新する必要があります。
外部データの扱い: 大容量のデータ（例：ファイルの内容）をどのように扱うかを決定する必要があります。著者は、コピー操作では「copy-on-write」戦略を推奨しています。
継承されたメタデータの扱い: 親リソースから継承されたメタデータ（例：アクセス制御ポリシー）をどのように扱うかを考慮する必要があります。
アトミック性の確保: 操作全体のアトミック性をどのように確保するかを検討する必要があります。データベーストランザクションの使用や、ポイントインタイムスナップショットの利用が推奨されています。

これらの課題に対処するため、著者は具体的な実装戦略を提案しています。例えば、Rustを用いてコピー操作を実装する場合、以下のようなコードが考えられます。

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CopyRequest {
    pub source_id: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub destination_id: Option<String>,
}

impl Service {
    pub async fn copy_resource(&self, req: CopyRequest) -> Result<Resource, Error> {
        // トランザクションの開始
        let mut tx = self.db.begin().await?;

        // ソースリソースの取得
        let source = self.get_resource_within_tx(&mut tx, &req.source_id).await?;

        // 新しい識別子の生成（または検証）
        let dest_id = match req.destination_id {
            Some(id) => {
                if self.resource_exists_within_tx(&mut tx, &id).await? {
                    return Err(Error::ResourceAlreadyExists);
                }
                id
            }
            None => generate_new_id(),
        };

        // リソースのコピー
        let new_resource = copy_resource(&source, &dest_id);

        // 子リソースのコピー
        self.copy_child_resources_within_tx(&mut tx, &source.id, &new_resource.id).await?;

        // 新しいリソースの保存
        self.save_resource_within_tx(&mut tx, &new_resource).await?;

        // トランザクションのコミット
        tx.commit().await?;

        Ok(new_resource)
    }
}

このコードは、データベーストランザクションを使用してコピー操作のアトミック性を確保し、子リソースも含めてコピーを行っています。また、目的地の識別子が指定されていない場合は新しい識別子を生成し、指定されている場合は既存リソースとの衝突をチェックしています。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

スケーラビリティとパフォーマンス: コピーや移動操作は、大量のデータを扱う可能性があるため、システムのスケーラビリティとパフォーマンスに大きな影響を与えます。特に、大規模なリソース階層を持つシステムでは、これらの操作の効率的な実装が重要になります。
データの整合性: コピーや移動操作中にデータの整合性を維持することは、システムの信頼性にとって重要です。特に、分散システムにおいては、これらの操作のアトミック性を確保することが大きな課題となります。
APIの進化と後方互換性: コピーや移動操作の導入は、APIの大きな変更となる可能性があります。既存のクライアントとの互換性を維持しつつ、これらの操作をどのように導入するかを慎重に検討する必要があります。
セキュリティとアクセス制御: リソースのコピーや移動は、セキュリティモデルに大きな影響を与える可能性があります。特に、異なるセキュリティコンテキスト間でリソースを移動する場合、適切なアクセス制御の実装が重要になります。
運用の複雑さ: コピーや移動操作の導入は、システムの運用複雑性を増大させる可能性があります。これらの操作のモニタリング、トラブルシューティング、そして必要に応じたロールバック手順の確立が重要になります。
イベント駆動アーキテクチャとの統合: コピーや移動操作をイベントとして発行することで、システム全体の一貫性を維持しやすくなります。例えば、リソースが移動されたときにイベントを発行し、関連するサービスがそれに反応して必要な更新を行うことができます。

結論

第17章「Copy and move」は、APIにおけるリソースのコピーと移動操作の重要性と、その実装に伴う複雑さを明確に示しています。著者の提案する設計原則は、これらの操作を安全かつ効果的に実装するための重要な指針となります。

コピー・移動を実装する前に確認すべき5点です。

コピーと移動操作は、カスタムメソッドとして実装すべきであり、標準的なCRUD操作では適切に処理できません。
これらの操作は、子リソースや関連リソースにも影響を与えるため、その影響範囲を慎重に考慮する必要があります。
データの整合性とアトミック性の確保が重要であり、適切なトランザクション管理やスナップショット機能の利用が推奨されます。
外部データやメタデータの扱い、特に大容量データの効率的な処理方法を考慮する必要があります。
これらの操作の導入は、システムの複雑性を増大させる可能性があるため、その必要性を慎重に評価する必要があります。

「ファイルを別フォルダに移動」をAPIで提供したら、権限チェックの漏れで他人のフォルダにファイルが移動できるバグを出したことがある。コピーと移動は見た目より危険だ。「本当に必要か」を3回問い直してから実装しても遅くない。

18 Batch operations

「API Design Patterns」の第18章「Batch operations」は、APIにおけるバッチ操作の重要性、設計原則、実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はバッチ操作が単なる利便性の向上だけでなく、APIの効率性、スケーラビリティ、そして全体的なシステムアーキテクチャにどのように影響を与えるかを明確に示しています。

バッチ操作の必要性と概要

著者は、個々のリソースに対する操作だけでなく、複数のリソースを一度に操作する必要性から議論を始めています。特に、データベースシステムにおけるトランザクションの概念を引き合いに出し、Webベースのシステムにおいても同様の原子性を持つ操作が必要であることを強調しています。

バッチ操作の重要性は、特にマイクロサービスアーキテクチャやクラウドネイティブ環境において顕著です。例えば、複数のサービス間でデータの一貫性を保ちながら大量のリソースを更新する必要がある場合、個別のAPI呼び出しでは効率が悪く、エラーハンドリングも複雑になります。バッチ操作を適切に設計することで、これらの問題を解決し、システム全体の効率性と信頼性を向上させることができます。

著者は、バッチ操作を実現するための主要な方法として、標準メソッド（Get、Create、Update、Delete）に対応するバッチバージョンのカスタムメソッドを提案しています。

BatchGet
BatchCreate
BatchUpdate
BatchDelete

これらのメソッドは、複数のリソースに対する操作を単一のAPI呼び出しで実行することを可能にします。

バッチ操作の設計原則

著者は、バッチ操作の設計に関していくつかの重要な原則を提示しています。

原子性: バッチ操作は全て成功するか、全て失敗するかのいずれかであるべきです。部分的な成功は許容されません。
コレクションに対する操作: バッチメソッドは、個々のリソースではなく、リソースのコレクションに対して操作を行うべきです。
結果の順序保持: バッチ操作の結果は、リクエストで指定されたリソースの順序を保持して返すべきです。
共通フィールドの最適化: リクエスト内で共通のフィールドを持つ場合、それらを「持ち上げ」て重複を避けるべきです。
複数の親リソースに対する操作: 必要に応じて、異なる親リソースに属するリソースに対するバッチ操作をサポートすべきです。

これらの原則は、バッチ操作の一貫性、効率性、そして使いやすさを確保する上で重要です。特に、原子性の保証は、システムの一貫性を維持し、複雑なエラーハンドリングを回避する上で重要です。

実装の詳細

著者は、各バッチ操作メソッドの実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

BatchGet: IDのリストを受け取り、対応するリソースのリストを返します。HTTP GETメソッドを使用し、IDはクエリパラメータとして渡されます。
BatchCreate: 作成するリソースのリストを受け取り、作成されたリソースのリストを返します。HTTP POSTメソッドを使用します。
BatchUpdate: 更新するリソースのリストとフィールドマスクを受け取り、更新されたリソースのリストを返します。HTTP POSTメソッドを使用します。
BatchDelete: 削除するリソースのIDリストを受け取り、操作の成功を示すvoid型を返します。HTTP POSTメソッドを使用します。

これらの実装詳細は、実際のシステム設計において有用です。例えば、Rustを用いてバッチ操作を実装する場合、以下のようなトレイトとメソッドが考えられます。

use async_trait::async_trait;

#[async_trait]
pub trait BatchService {
    async fn batch_get(&self, ids: &[String]) -> Result<Vec<Resource>, Error>;
    async fn batch_create(&self, resources: &[Resource]) -> Result<Vec<Resource>, Error>;
    async fn batch_update(&self, updates: &[ResourceUpdate]) -> Result<Vec<Resource>, Error>;
    async fn batch_delete(&self, ids: &[String]) -> Result<(), Error>;
}

pub struct ResourceUpdate {
    pub id: String,
    pub update_mask: Vec<String>,
    pub resource: Resource,
}

impl BatchService for ServiceImpl {
    async fn batch_get(&self, ids: &[String]) -> Result<Vec<Resource>, Error> {
        // トランザクションの開始
        let mut tx = self.db.begin().await?;

        let mut resources = Vec::with_capacity(ids.len());
        for id in ids {
            let resource = self.get_resource_within_tx(&mut tx, id).await?;
            // 1つでも失敗したら全体を失敗とする
            resources.push(resource);
        }

        tx.commit().await?;

        Ok(resources)
    }
}

この実装例では、batch_getメソッドがトランザクションを使用して原子性を確保し、1つのリソースの取得に失敗した場合は全体を失敗として扱っています。

バッチ操作の影響とトレードオフ

著者は、バッチ操作の導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

パフォーマンスとスケーラビリティ: バッチ操作は、ネットワーク呼び出しの回数を減らし、全体的なスループットを向上させる可能性があります。しかし、大規模なバッチ操作は、サーバーリソースに大きな負荷をかける可能性もあります。
エラーハンドリングの複雑さ: 原子性を保証することで、エラーハンドリングが簡素化されます。しかし、全て成功するか全て失敗するかの動作は、一部のユースケースでは不便な場合があります。
API設計の一貫性: バッチ操作の導入は、API全体の設計に一貫性をもたらす可能性がありますが、同時に新たな複雑さも導入します。
システムの復元力: 適切に設計されたバッチ操作は、システムの復元力を向上させる可能性があります。例えば、一時的な障害が発生した場合、バッチ全体をリトライすることで回復が容易になります。
モニタリングと可観測性: バッチ操作は、システムの挙動を監視し理解することをより複雑にする可能性があります。個々の操作の詳細が見えにくくなるため、適切なロギングと監視戦略が重要になります。

これらの影響とトレードオフを考慮しながら、バッチ操作の導入を検討する必要があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの統合: バッチ操作は、マイクロサービス間のデータ一貫性を維持する上で重要な役割を果たします。例えば、複数のサービスにまたがるリソースの更新を、単一のトランザクションとして扱うことができます。
イベント駆動アーキテクチャとの連携: バッチ操作の結果をイベントとして発行することで、システム全体の反応性と柔軟性を向上させることができます。
キャッシュ戦略: バッチ操作は、キャッシュの一貫性維持を複雑にする可能性があります。適切なキャッシュ無効化戦略が必要になります。
レート制限とクォータ管理: バッチ操作は、リソース使用量を急激に増加させる可能性があるため、適切なレート制限とクォータ管理が重要になります。
非同期処理との統合: 長時間実行されるバッチ操作の場合、非同期処理パターン（例：ポーリング、Webhookなど）と統合することで、クライアントの応答性を向上させることができます。

結論

第18章「Batch operations」は、APIにおけるバッチ操作の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの効率性、スケーラビリティ、そして全体的なシステムアーキテクチャを大きく向上させる可能性があります。

バッチ操作を設計する上での原則を整理します。

バッチ操作は、複数のリソースに対する操作を効率的に行うための強力なツールです。
原子性の保証は、システムの一貫性を維持し、エラーハンドリングを簡素化する上で重要です。
バッチ操作の設計には、結果の順序保持、共通フィールドの最適化、複数親リソースのサポートなど、いくつかの重要な原則があります。
バッチ操作の導入は、システム全体のパフォーマンス、スケーラビリティ、そして運用性に大きな影響を与えます。
バッチ操作の適切な実装には、トランザクション管理、エラーハンドリング、モニタリングなど、複数の側面を考慮する必要があります。

ただしバッチ操作の導入には慎重な検討が必要です。全ての操作をバッチ化することが適切とは限らず、システムの要件や制約に基づいて適切なバランスを取る必要があります。また、バッチ操作の導入に伴う複雑さの増加を管理するために、適切なモニタリング、ロギング、そしてエラーハンドリング戦略を確立することが重要です。

最後に、バッチ操作の設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単にAPIの機能を拡張するだけでなく、システム全体の効率性、スケーラビリティ、そして運用効率の向上にも大きく貢献します。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

バッチ操作の適切な実装は、システムの進化と拡張を容易にし、長期的な保守性を向上させます。API設計者とシステム設計者は、これらの原則を深く理解し、実践することで、より堅牢で効率的なシステムを構築することができるでしょう。特に、大規模なデータ処理や複雑なビジネスロジックを持つシステムにおいて、バッチ操作は重要な役割を果たします。適切に設計されたバッチ操作は、システムの性能を大幅に向上させ、運用コストを削減し、ユーザー体験を向上させる強力なツールとなります。

19 Criteria-based deletion

「API Design Patterns」の第19章「Criteria-based deletion」は、APIにおける条件に基づく削除操作の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者は条件に基づく削除操作（purge操作）が単なる利便性の向上だけでなく、APIの柔軟性、効率性、そして全体的なシステムの安全性にどのように影響を与えるかを明確に示しています。

条件に基づく削除の必要性と概要

著者は、バッチ削除操作の限界から議論を始めています。バッチ削除では、削除対象のリソースのIDを事前に知っている必要がありますが、実際の運用では特定の条件に合致するすべてのリソースを削除したい場合が多々あります。例えば、アーカイブされたすべてのチャットルームを削除するような操作です。

この問題に対処するため、著者は「purge」と呼ばれる新しいカスタムメソッドを提案しています。purgeメソッドは、フィルタ条件を受け取り、その条件に合致するすべてのリソースを一度に削除します。これにより、複数のAPI呼び出し（リソースの一覧取得と削除の組み合わせ）を1回のAPI呼び出しに置き換えることができ、効率性と一貫性が向上します。

しかし、著者はこの操作の危険性も明確に指摘しています。purge操作は、ユーザーが意図せずに大量のデータを削除してしまう可能性があるため、慎重に設計し、適切な安全機構を組み込む必要があります。

purge操作の設計と実装

著者は、purge操作の安全な実装のために以下の重要な要素を提案しています。

forceフラグ: デフォルトでは削除を実行せず、プレビューモードとして動作します。実際に削除を行うには、明示的にforceフラグをtrueに設定する必要があります。
purgeCount: 削除対象となるリソースの数を返します。プレビューモードでは概算値を返すこともあります。
purgeSample: 削除対象となるリソースのサンプルセットを返します。これにより、ユーザーは削除対象が意図したものであるかを確認できます。

これらの要素を組み合わせることで、APIは柔軟かつ安全な条件付き削除機能を提供することができます。

著者は、purge操作の実装に関して詳細なガイダンスを提供しています。特に注目すべき点は以下の通りです。

フィルタリング: purge操作のフィルタは、標準的なリスト操作のフィルタと同じように動作すべきです。これにより、APIの一貫性が保たれます。
デフォルトの動作: 安全性を確保するため、デフォルトではプレビューモードとして動作し、実際の削除は行いません。
結果の一貫性: プレビューと実際の削除操作の間でデータが変更される可能性があるため、完全な一貫性は保証できません。この制限をユーザーに明確に伝える必要があります。

これらの原則を適用した、Rustでのpurge操作の実装例を以下に示します。

use serde::{Deserialize, Serialize};
use thiserror::Error;

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PurgeRequest {
    pub parent: String,
    pub filter: String,
    pub force: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PurgeResponse {
    pub purge_count: usize,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub purge_sample: Option<Vec<String>>,
}

#[derive(Error, Debug)]
pub enum PurgeError {
    #[error("filter is required")]
    FilterRequired,
}

impl Service {
    pub async fn purge_messages(&self, req: &PurgeRequest) -> Result<PurgeResponse, Error> {
        // フィルタの検証
        if req.filter.is_empty() {
            return Err(PurgeError::FilterRequired.into());
        }

        // マッチするリソースの取得
        let matching_resources = self.get_matching_resources(&req.parent, &req.filter).await?;

        let response = PurgeResponse {
            purge_count: matching_resources.len(),
            purge_sample: Some(get_sample(&matching_resources, 100)),
        };

        // 実際の削除操作
        if req.force {
            self.delete_resources(&matching_resources).await?;
        }

        Ok(response)
    }
}

この実装例では、forceフラグがfalseの場合はプレビューのみを行い、trueの場合に実際の削除を実行します。また、削除対象のサンプルを返すことで、ユーザーが意図した操作であるかを確認できるようにしています。

purge操作の影響とトレードオフ

著者は、purge操作の導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

パフォーマンスと効率性: purge操作は、複数のAPI呼び出しを1回の呼び出しに置き換えることで、全体的な効率を向上させます。しかし、大量のデータを一度に処理する必要があるため、サーバーリソースに大きな負荷をかける可能性があります。
安全性とユーザビリティのバランス: デフォルトでプレビューモードとして動作することで安全性を確保していますが、これは同時にユーザーが2回のAPI呼び出しを行う必要があることを意味します。このトレードオフを適切に管理する必要があります。
データの一貫性: プレビューと実際の削除操作の間でデータが変更される可能性があるため、完全な一貫性を保証することは困難です。この制限をユーザーに明確に伝え、適切に管理する必要があります。
エラー処理の複雑さ: 大量のリソースを一度に削除する際、一部のリソースの削除に失敗した場合の処理が複雑になる可能性があります。部分的な成功をどのように扱うかを慎重に設計する必要があります。
監視と可観測性: purge操作は、システムの状態を大きく変更する可能性があるため、適切な監視と監査メカニズムが不可欠です。どのような条件で、どれだけのリソースが削除されたかを追跡できるようにする必要があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの統合: purge操作は、複数のマイクロサービスにまたがるデータの一貫性を維持する上で重要な役割を果たす可能性があります。例えば、ユーザーデータの削除（GDPR対応など）や、大規模なデータクリーンアップ操作に利用できます。
イベント駆動アーキテクチャとの連携: purge操作の結果をイベントとして発行することで、関連するシステムコンポーネントが適切に反応し、全体的な一貫性を維持することができます。
バックグラウンドジョブとしての実装: 大規模なpurge操作は、非同期のバックグラウンドジョブとして実装することを検討すべきです。これにより、クライアントのタイムアウトを回避し、システムの応答性を維持することができます。
段階的な削除戦略: 大量のデータを一度に削除するのではなく、段階的に削除を行う戦略を検討すべきです。これにより、システムへの影響を最小限に抑えつつ、大規模な削除操作を安全に実行することができます。
監査とコンプライアンス: purge操作は、監査とコンプライアンスの観点から重要です。どのデータがいつ、誰によって、どのような条件で削除されたかを追跡できるようにする必要があります。

結論

第19章「Criteria-based deletion」は、条件に基づく削除操作（purge操作）の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性と効率性を向上させる一方で、システムの安全性と整合性を維持することを目指しています。

purge操作を安全に実装するための原則です。

purge操作は、条件に基づいて複数のリソースを一度に削除する強力なツールですが、慎重に設計し、適切な安全機構を組み込む必要があります。
デフォルトでプレビューモードとして動作し、実際の削除には明示的な承認（forceフラグ）を要求することで、意図しない大規模削除を防ぐことができます。
削除対象のリソース数とサンプルを提供することで、ユーザーが操作の影響を事前に評価できるようにすることが重要です。
データの一貫性の保証が難しいため、この制限をユーザーに明確に伝える必要があります。
purge操作の導入は、システム全体のパフォーマンス、スケーラビリティ、そして運用性に大きな影響を与える可能性があるため、慎重に検討する必要があります。

ただしpurge操作の導入には慎重な検討が必要です。その強力な機能ゆえに、システムの安全性とデータの整合性に大きなリスクをもたらす可能性があります。したがって、purge操作は本当に必要な場合にのみ導入し、適切な制限と監視メカニズムを併せて実装することが重要です。

最後に、purge操作の設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単にAPIの機能を拡張するだけでなく、システム全体のデータ管理戦略、セキュリティポリシー、そして運用プラクティスにも大きな影響を与えます。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

purge操作の適切な実装は、システムのデータ管理能力を大幅に向上させ、運用効率を高める可能性があります。しかし、同時にそれは大きな責任を伴います。API設計者とシステム設計者は、これらの操作の影響を深く理解し、適切なサフェガードを実装することで、より堅牢で効率的、かつ安全なシステムを構築することができるでしょう。特に、大規模なデータ管理や複雑なビジネスロジックを持つシステムにおいて、purge操作は重要な役割を果たす可能性がありますが、その導入には慎重な検討と綿密な計画が不可欠です。

20 Anonymous writes

「API Design Patterns」の第20章「Anonymous writes」は、APIにおける匿名データの書き込みの概念、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者は従来のリソース指向のAPIデザインでは対応が難しい匿名データの取り扱いについて、新しいアプローチを提案し、それがシステム全体のアーキテクチャと運用にどのように影響を与えるかを明確に示しています。

匿名データの必要性と概要

著者は、これまでのAPI デザインパターンでは全てのデータをリソースとして扱ってきたことを指摘し、この approach が全てのシナリオに適しているわけではないという問題提起から議論を始めています。特に、時系列データやログエントリのような、個別に識別や操作する必要のないデータの取り扱いについて、新しいアプローチの必要性を強調しています。

この問題は、特に大規模なデータ分析システムやクラウドネイティブな環境において顕著です。例えば、IoTデバイスから大量のセンサーデータを収集する場合や、マイクロサービス間のイベントログを記録する場合など、個々のデータポイントよりも集計結果や傾向分析が重要となるシナリオが多々あります。

著者は、このような匿名データを扱うための新しいカスタムメソッド「write」を提案しています。このメソッドの主な特徴は以下の通りです。

データは一意の識別子を持たず、個別にアドレス指定できない。
書き込まれたデータは、主に集計や分析の目的で使用される。
個々のデータエントリの取得、更新、削除は想定されていない。

この概念は、現代のビッグデータ分析システムやイベント駆動アーキテクチャと非常に親和性が高く、特にクラウドネイティブな環境での応用が期待されます。

write メソッドの実装

著者は、write メソッドの実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

戻り値: write メソッドは void を返すべきです。これは、個々のデータエントリが識別可能でないため、新しく作成されたリソースを返す必要がないためです。
ペイロード: データは entry フィールドを通じて送信されます。これは標準の create メソッドの resource フィールドに相当します。
URL構造: コレクションをターゲットとするべきです。例えば、/chatRooms/1/statEntries:write のような形式です。
一貫性: write メソッドは即座に応答を返すべきですが、データが即座に読み取り可能である必要はありません。これは、大規模なデータ処理パイプラインの特性を反映しています。

これらの原則を適用した、Rustでのwrite メソッドの実装例を以下に示します。

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChatRoomStatEntry {
    pub name: String,
    pub value: serde_json::Value,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WriteChatRoomStatEntryRequest {
    pub parent: String,
    pub entry: ChatRoomStatEntry,
}

impl Service {
    pub async fn write_chat_room_stat_entry(&self, req: &WriteChatRoomStatEntryRequest) -> Result<(), Error> {
        // データの検証
        validate_entry(&req.entry)?;

        // データ処理パイプラインへの送信
        self.data_pipeline.send(&req.parent, &req.entry).await?;

        // 即座に成功を返す
        Ok(())
    }
}

この実装例では、データの検証を行った後、非同期のデータ処理パイプラインにデータを送信しています。メソッドは即座に応答を返し、クライアントはデータが処理されるのを待つ必要がありません。

一貫性と運用上の考慮事項

著者は、write メソッドの一貫性モデルについて重要な指摘をしています。従来のリソース指向のAPIでは、データの書き込み後即座にそのデータが読み取り可能であることが期待されますが、write メソッドではこの即時一貫性は保証されません。

これは、大規模なデータ処理システムの現実的な運用を反映しています。例えば、時系列データベースやビッグデータ処理システムでは、データの取り込みと処理に時間差があるのが一般的です。著者は、この非同期性を明示的に設計に組み込むことで、より効率的で拡張性の高いシステムが構築できると主張しています。

運用の観点から見ると、この設計には以下のような利点があります。

スケーラビリティの向上: データの取り込みと処理を分離することで、それぞれを独立してスケールさせることができます。
システムの回復力: データ処理パイプラインに一時的な問題が発生しても、データの取り込み自体は継続できます。
バッファリングと負荷平準化: 取り込んだデータをバッファリングすることで、下流のシステムへの負荷を平準化できます。
運用の柔軟性: データ処理ロジックを変更する際に、APIインターフェースを変更せずに済みます。

著者は、クライアントにデータの処理状況を伝えるために、HTTP 202 Accepted ステータスコードの使用を推奨しています。これは、データが受け入れられたが、まだ完全に処理されていないことを示す適切な方法です。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

イベント駆動アーキテクチャとの親和性: write メソッドは、イベントソーシングやCQRSパターンと非常に相性が良いです。例えば、マイクロサービス間の非同期通信や、イベントストリームの生成に活用できます。
観測可能性の向上: 匿名データの書き込みを明示的に設計に組み込むことで、システムの振る舞いをより詳細に観測できるようになります。例えば、各サービスの内部状態の変化を時系列データとして記録し、後で分析することが容易になります。
コンプライアンスと監査: 匿名データの書き込みを標準化することで、システム全体の動作ログを一貫した方法で収集できます。これは、コンプライアンス要件の遵守や、システムの監査に役立ちます。
パフォーマンスチューニング: 集計データの収集を最適化することで、システム全体のパフォーマンスプロファイルを詳細に把握し、ボトルネックの特定や最適化が容易になります。
A/Bテストとフィーチャーフラグ: 匿名データを活用することで、新機能の段階的なロールアウトや、A/Bテストの結果収集を効率的に行うことができます。

結論

第20章「Anonymous writes」は、APIにおける匿名データの取り扱いの重要性と、その適切な実装方法を明確に示しています。著者の提案するwrite メソッドは、従来のリソース指向のAPIデザインを補完し、より柔軟で拡張性の高いシステム設計を可能にします。

匿名データを扱う際の設計原則です。

全てのデータをリソースとして扱う必要はなく、匿名データの概念を導入することで、より効率的なデータ処理が可能になります。
write メソッドは、即時一貫性を犠牲にする代わりに、高いスケーラビリティと柔軟性を提供します。
匿名データの取り扱いは、大規模なデータ分析システムやイベント駆動アーキテクチャと非常に親和性が高いです。
システムの観測可能性、コンプライアンス、パフォーマンスチューニングなど、運用面でも多くの利点があります。
write メソッドの導入には、システム全体のアーキテクチャと処理パイプラインの設計を考慮する必要があります。

大規模なデータ処理やイベント駆動システムでは特に有用なパターンです。

ただしwrite メソッドの導入には慎重な検討も必要です。即時一貫性が重要なユースケースでは、従来のリソース指向のアプローチが適している場合もあります。また、匿名データの取り扱いは、データの追跡やデバッグを複雑にする可能性があるため、適切なモニタリングとログ記録の戦略が不可欠です。

最後に、匿名データの取り扱いはシステム全体のアーキテクチャと密接に関連しています。write メソッドの導入は、単にAPIの機能を拡張するだけでなく、システム全体のデータフロー、処理パイプライン、そして運用プラクティスにも大きな影響を与えます。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

この章の内容は、特に大規模で複雑なシステムの設計において重要です。匿名データの適切な取り扱いは、システムの拡張性、柔軟性、そして運用効率を大きく向上させる可能性があります。API設計者とシステム設計者は、これらの概念を深く理解し、適切に応用することで、より堅牢で効率的なシステムを構築することができるでしょう。

「API Design Patterns」の第21章「Pagination」は、APIにおけるページネーションの重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はページネーションが単なる機能の追加ではなく、APIの使いやすさ、効率性、そして全体的なシステムのスケーラビリティにどのように影響を与えるかを明確に示しています。

ページネーションの必要性と概要

著者は、大規模なデータセットを扱う際のページネーションの必要性から議論を始めています。特に、1億件のデータを一度に返そうとすることの問題点を指摘し、ページネーションがこの問題にどのように対処するかを説明しています。ページネーションは、大量のデータを管理可能な「チャンク」に分割し、クライアントが必要に応じてデータを取得できるようにする方法です。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、複数のマイクロサービスが協調して動作する環境では、各サービスが大量のデータを効率的に処理し、ネットワーク帯域幅を最適化する必要があります。ページネーションは、このような環境でのデータ転送を最適化し、システム全体のパフォーマンスと応答性を向上させる重要な手段となります。

著者は、ページネーションの基本的な構造として以下の要素を提案しています。

pageToken: 次のページを取得するためのトークン
maxPageSize: クライアントが要求する最大ページサイズ
nextPageToken: サーバーが返す次のページのトークン

これらの要素を組み合わせることで、APIは大規模なデータセットを効率的に管理し、クライアントに段階的に提供することができます。

ページネーションの実装

著者は、ページネーションの実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

最大ページサイズ vs 正確なページサイズ: 著者は、正確なページサイズではなく最大ページサイズを使用することを推奨しています。これにより、サーバーは要求されたサイズよりも小さいページを返すことができ、パフォーマンスと効率性が向上します。
ページトークンの不透明性: ページトークンは、クライアントにとって意味を持たない不透明な文字列であるべきです。これにより、サーバー側で実装の詳細を変更する柔軟性が確保されます。
一貫性の確保: ページネーション中にデータが変更される可能性があるため、完全な一貫性を保証することは難しい場合があります。著者は、この制限を明確に文書化することを推奨しています。
ページトークンの有効期限: ページトークンに有効期限を設定することで、リソースの効率的な管理が可能になります。

これらの原則を適用した、Rustでのページネーションの実装例を以下に示します。

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ListResourcesRequest {
    pub page_token: String,
    pub max_page_size: i32,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ListResourcesResponse {
    pub resources: Vec<Resource>,
    pub next_page_token: String,
}

impl Service {
    pub async fn list_resources(&self, req: &ListResourcesRequest) -> Result<ListResourcesResponse, Error> {
        // ページトークンのデコードと検証
        let offset = decode_page_token(&req.page_token)?;

        // リソースの取得
        let limit = req.max_page_size.min(100) as usize; // 最大100件に制限
        let mut resources = self.repository.get_resources(offset, limit + 1).await?;

        // 次のページトークンの生成
        let next_page_token = if resources.len() > limit {
            resources.truncate(limit);
            encode_page_token(offset + limit)
        } else {
            String::new()
        };

        Ok(ListResourcesResponse {
            resources,
            next_page_token,
        })
    }
}

この実装例では、ページトークンを使用してオフセットを管理し、最大ページサイズを制限しています。また、次のページがあるかどうかを判断するために、要求された制限よりも1つ多くのリソースを取得しています。

ページネーションの影響とトレードオフ

著者は、ページネーションの導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

パフォーマンスとスケーラビリティ: ページネーションは、大規模なデータセットを扱う際のパフォーマンスを大幅に向上させます。しかし、適切に実装されていない場合（例：オフセットベースのページネーション）、データベースへの負荷が増大する可能性があります。
一貫性と可用性のバランス: 完全な一貫性を保証しようとすると、システムの可用性が低下する可能性があります。著者は、このトレードオフを明確に理解し、適切なバランスを取ることの重要性を強調しています。
クライアント側の複雑性: ページネーションは、クライアント側の実装を複雑にする可能性があります。特に、全データを取得する必要がある場合、クライアントは複数のリクエストを管理する必要があります。
キャッシュ戦略: ページネーションは、キャッシュ戦略に影響を与えます。各ページを個別にキャッシュする必要があり、データの更新頻度によってはキャッシュの有効性が低下する可能性があります。

これらの影響とトレードオフを考慮しながら、ページネーションの実装を検討する必要があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの統合: ページネーションは、マイクロサービス間でのデータ転送を最適化する上で重要な役割を果たします。各サービスが大量のデータを効率的に処理し、ネットワーク帯域幅を最適化することで、システム全体のパフォーマンスが向上します。
イベント駆動アーキテクチャとの連携: ページネーションは、イベントストリームの処理にも応用できます。大量のイベントを処理する際に、ページネーションを使用することで、消費者が管理可能なチャンクでイベントを処理できるようになります。
データの一貫性と鮮度: ページネーション中にデータが変更される可能性があるため、データの一貫性と鮮度のバランスを取る必要があります。特に、リアルタイム性が求められるシステムでは、この点に注意が必要です。
クエリパフォーマンスの最適化: ページネーションの実装方法によっては、データベースへの負荷が増大する可能性があります。特に、オフセットベースのページネーションは大規模なデータセットで問題が発生する可能性があります。カーソルベースのページネーションなど、より効率的な方法を検討する必要があります。
レスポンスタイムの一貫性: ページサイズを固定することで、各リクエストのレスポンスタイムをより一貫したものにすることができます。これは、システムの予測可能性と信頼性を向上させる上で重要です。
エラー処理とリトライ戦略: ページネーションを使用する際は、ネットワークエラーやタイムアウトに対する適切なエラー処理とリトライ戦略が重要になります。特に、長時間にわたるデータ取得プロセスでは、この点に注意が必要です。
モニタリングと可観測性: ページネーションの使用パターンを監視することで、システムの使用状況やボトルネックを特定することができます。例えば、特定のページサイズやフィルタ条件が頻繁に使用されている場合、それらに対して最適化を行うことができます。

ページネーションと全体的なシステムアーキテクチャ

ページネーションの設計は、システム全体のアーキテクチャに大きな影響を与えます。以下の点について考慮する必要があります。

データモデルとインデックス設計: 効率的なページネーションを実現するためには、適切なデータモデルとインデックス設計が不可欠です。特に、大規模なデータセットを扱う場合、この点が重要になります。
キャッシュ戦略: ページネーションを使用する場合、各ページを個別にキャッシュする必要があります。これにより、キャッシュ戦略が複雑になる可能性があります。特に、データの更新頻度が高い場合、キャッシュの有効性が低下する可能性があります。
負荷分散とスケーリング: ページネーションを使用することで、システムの負荷をより均等に分散させることができます。これにより、システムのスケーラビリティが向上します。
バックエンドサービスの設計: ページネーションを効率的に実装するためには、バックエンドサービスの設計を適切に行う必要があります。特に、データベースクエリの最適化や、ページトークンの生成と管理が重要になります。
API設計の一貫性: ページネーションの設計は、API全体の設計と一貫性を保つ必要があります。例えば、ページネーションパラメータの命名規則や、レスポンス形式などを統一することが重要です。

結論

第21章「Pagination」は、APIにおけるページネーションの重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの使いやすさ、効率性、そして全体的なシステムのスケーラビリティを大きく向上させる可能性があります。

ページネーション設計の原則を5つ挙げます。

ページネーションは、大規模なデータセットを扱う際に不可欠な機能です。
最大ページサイズを使用し、正確なページサイズを保証しないことで、システムの柔軟性と効率性が向上します。
ページトークンは不透明であるべきで、クライアントはその内容を理解したり操作したりする必要はありません。
データの一貫性と可用性のバランスを取ることが重要です。完全な一貫性を保証することは難しい場合があり、この制限を明確に文書化する必要があります。
ページネーションの設計は、システム全体のアーキテクチャ、パフォーマンス、スケーラビリティに大きな影響を与えます。

オフセットベースのページネーションで10万件目を取ろうとしたとき、DBが悲鳴を上げた。カーソルベースに移行するのに、クライアント全員に説明して回る羽目になった。最初から「次のページトークン」方式にしておけば、この苦労はなかった。

22 Filtering

「API Design Patterns」の第22章「Filtering」は、APIにおけるフィルタリング機能の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はフィルタリングが単なる便利な機能ではなく、APIの効率性、使いやすさ、そして全体的なシステムのパフォーマンスにどのように影響を与えるかを明確に示しています。

フィルタリングの必要性と概要

著者は、標準的なリスト操作だけでは特定の条件に合致するリソースのみを取得することが困難であるという問題提起から議論を始めています。大規模なデータセットを扱う現代のシステムにおいて、クライアントが全てのリソースを取得してから必要なデータをフィルタリングするというアプローチは、非効率的であり、システムリソースの無駄遣いにつながります。

この問題は、特にマイクロサービスアーキテクチャやクラウドネイティブ環境において顕著です。例えば、複数のマイクロサービスが協調して動作する環境では、各サービスが大量のデータを効率的に処理し、ネットワーク帯域幅を最適化する必要があります。サーバーサイドでのフィルタリングは、このような環境でのデータ転送を最適化し、システム全体のパフォーマンスと応答性を向上させる重要な手段となります。

著者は、フィルタリングの基本的な実装として、標準的なリストリクエストにfilterフィールドを追加することを提案しています。このフィールドを通じて、クライアントは必要なデータの条件を指定し、サーバーはその条件に合致するリソースのみを返すことができます。

フィルタリングの実装

著者は、フィルタリングの実装に関して詳細なガイダンスを提供しています。特に注目すべき点は以下の通りです。

フィルター表現の構造: 著者は、構造化されたフィルター（例：JSONオブジェクト）ではなく、文字列ベースのフィルター表現を推奨しています。これにより、APIの柔軟性が向上し、将来的な拡張が容易になります。
実行時間の考慮: フィルター式の評価は、単一のリソースのコンテキスト内で完結すべきであり、外部データソースへのアクセスや複雑な計算を含むべきではありません。これにより、フィルタリング操作の予測可能性と効率性が確保されます。
配列要素のアドレス指定: 著者は、配列内の特定の位置の要素を参照するフィルタリングを避け、代わりに配列内の要素の存在をチェックするアプローチを推奨しています。これにより、データの順序に依存しない柔軟なフィルタリングが可能になります。
厳格性: フィルター式の解釈は厳格であるべきで、あいまいな表現や型の不一致は許容せず、エラーとして扱うべきです。これにより、フィルタリングの信頼性と予測可能性が向上します。
カスタム関数: 基本的なフィルタリング機能では不十分な場合に備えて、カスタム関数の導入を提案しています。これにより、複雑なフィルタリング要件にも対応できます。

これらの原則を適用した、Rustでのフィルタリング実装の例を以下に示します。

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ListResourcesRequest {
    pub filter: String,
    pub max_page_size: i32,
    pub page_token: String,
}

impl Service {
    pub async fn list_resources(&self, req: &ListResourcesRequest) -> Result<ListResourcesResponse, Error> {
        let filter = parse_filter(&req.filter)
            .map_err(|e| Error::InvalidFilter(e.to_string()))?;

        let resources = self.repository.get_resources().await?;

        let filtered_resources: Vec<Resource> = resources
            .into_iter()
            .filter(|resource| filter.evaluate(resource))
            .collect();

        // ページネーションの処理
        // ...
        let next_page_token = String::new();

        Ok(ListResourcesResponse {
            resources: filtered_resources,
            next_page_token,
        })
    }
}

この実装例では、フィルター文字列をパースし、各リソースに対して評価関数を適用しています。フィルターの解析と評価は厳格に行われ、無効なフィルターや型の不一致はエラーとして扱われます。

フィルタリングの影響とトレードオフ

著者は、フィルタリング機能の導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

パフォーマンスとスケーラビリティ: サーバーサイドでのフィルタリングは、ネットワーク帯域幅の使用を最適化し、クライアントの処理負荷を軽減します。しかし、複雑なフィルター式の評価はサーバーリソースを消費する可能性があります。
柔軟性と複雑性のバランス: 文字列ベースのフィルター表現は高い柔軟性を提供しますが、解析と評価の複雑さが増加します。これは、エラーハンドリングとセキュリティの観点から慎重に管理する必要があります。
一貫性と可用性: フィルタリング結果の一貫性を保証することは、特に分散システムにおいて課題となります。データの更新とフィルタリング操作のタイミングによっては、結果が異なる可能性があります。
セキュリティの考慮: フィルター式の評価は、潜在的なセキュリティリスクを伴います。インジェクション攻撃や過度に複雑なクエリによるDoS攻撃の可能性に注意する必要があります。

これらのトレードオフを適切に管理することが、フィルタリング機能の成功的な実装の鍵となります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの統合: フィルタリングはマイクロサービス間のデータ交換を最適化する上で重要な役割を果たします。各サービスが必要最小限のデータのみを要求・提供することで、システム全体の効率性が向上します。
クエリ最適化: フィルタリング機能は、データベースクエリの最適化と密接に関連しています。効率的なインデックス設計やクエリプランの最適化が、フィルタリングのパフォーマンスに大きな影響を与えます。
キャッシュ戦略: フィルタリング結果のキャッシングは、システムのパフォーマンスを大幅に向上させる可能性があります。しかし、キャッシュの有効性とデータの鮮度のバランスを取ることが課題となります。
バージョニングと後方互換性: フィルター構文の進化は、APIのバージョニング戦略に影響を与えます。新機能の追加や変更が既存のクライアントに影響を与えないよう、慎重に管理する必要があります。
モニタリングと可観測性: フィルタリング操作のパフォーマンスと使用パターンを監視することで、システムの最適化機会を特定できます。例えば、頻繁に使用されるフィルターパターンに対して特別な最適化を行うことが可能になります。

フィルタリングとシステムアーキテクチャ

フィルタリング機能の設計は、システム全体のアーキテクチャに大きな影響を与えます。以下の点について考慮する必要があります。

データモデルとスキーマ設計: 効率的なフィルタリングを実現するためには、適切なデータモデルとスキーマ設計が不可欠です。フィルタリングが頻繁に行われるフィールドに対しては、適切なインデックスを設定する必要があります。
分散システムにおけるフィルタリング: マイクロサービスアーキテクチャにおいて、フィルタリングはしばしば複数のサービスにまたがって行われる必要があります。このような場合、フィルタリングロジックの配置と実行方法を慎重に設計する必要があります。
リアルタイムシステムとの統合: ストリーミングデータや実時間性の高いシステムにおいて、フィルタリングはより複雑になります。データの到着と処理のタイミングを考慮したフィルタリング戦略が必要となります。
セキュリティアーキテクチャ: フィルタリング機能は、データアクセス制御と密接に関連しています。ユーザーの権限に基づいて、フィルタリング可能なデータの範囲を制限する必要があります。
エラー処理とレジリエンス: フィルタリング操作の失敗がシステム全体に与える影響を最小限に抑えるため、適切なエラー処理とフォールバック機構を実装する必要があります。

結論

第22章「Filtering」は、APIにおけるフィルタリング機能の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの使いやすさ、効率性、そして全体的なシステムのパフォーマンスを大きく向上させる可能性があります。

フィルタリング機能の設計で守るべき原則です。

フィルタリングは、大規模なデータセットを扱う現代のシステムにおいて不可欠な機能です。
文字列ベースのフィルター表現を使用することで、APIの柔軟性と拡張性が向上します。
フィルター式の評価は、単一のリソースのコンテキスト内で完結し、外部データソースへのアクセスを避けるべきです。
フィルター式の解釈は厳格であるべきで、あいまいな表現や型の不一致はエラーとして扱うべきです。
カスタム関数の導入により、複雑なフィルタリング要件にも対応できます。

フィルター構文を自由度高く設計したら、SQLインジェクションに近い脆弱性を作り込んだことがある。「ユーザー入力をそのままクエリに渡さない」は当たり前だが、フィルター式という形で油断した。表現力とセキュリティはトレードオフだ。

23 Importing and exporting

「API Design Patterns」の第23章「Importing and exporting」は、APIにおけるデータのインポートとエクスポートの重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はインポートとエクスポート機能が単なるデータ移動の手段ではなく、APIの効率性、柔軟性、そして全体的なシステムアーキテクチャにどのように影響を与えるかを明確に示しています。

インポートとエクスポートの必要性と概要

著者は、大規模なデータセットを扱う現代のシステムにおいて、効率的なデータの移動が不可欠であるという問題提起から議論を始めています。従来のアプローチでは、クライアントアプリケーションがAPIからデータを取得し、それを外部ストレージに保存する（またはその逆）という方法が一般的でした。しかし、このアプローチには大きな問題があります。特に、データがAPIサーバーとストレージシステムの近くに位置しているにもかかわらず、クライアントアプリケーションが遠隔地にある場合、大量のデータ転送が必要となり、効率が著しく低下します。

著者は、この問題を解決するために、APIサーバーが直接外部ストレージシステムとやり取りするカスタムメソッドを導入することを提案しています。具体的には、importとexportという2つのカスタムメソッドです。これらのメソッドは、データの転送だけでなく、APIリソースとバイトデータ間の変換も担当します。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、複数のマイクロサービスが協調して動作する環境では、各サービスが大量のデータを効率的に処理し、ネットワーク帯域幅を最適化する必要があります。インポート/エクスポート機能を適切に設計することで、サービス間のデータ移動を最適化し、システム全体のパフォーマンスと応答性を向上させることができます。

インポートとエクスポートの実装

著者は、インポートとエクスポートの実装に関して詳細なガイダンスを提供しています。特に注目すべき点は以下の通りです。

構造の分離: 著者は、データの転送と変換を別々の設定インターフェースで管理することを提案しています。具体的には、DataSource/DataDestinationインターフェースでデータの移動を、InputConfig/OutputConfigインターフェースでデータの変換を管理します。この分離により、システムの柔軟性と再利用性が大幅に向上します。
長時間実行操作（LRO）: インポートとエクスポート操作は時間がかかる可能性があるため、著者はこれらの操作をLROとして実装することを推奨しています。これにより、クライアントは操作の進行状況を追跡し、完了を待つことができます。
一貫性の考慮: エクスポート操作中にデータが変更される可能性があるため、著者はデータの一貫性について慎重に検討しています。完全な一貫性を保証できない場合、「スメア」（一時的な不整合）が発生する可能性があることを明確に示しています。
識別子の扱い: インポート時に識別子をどのように扱うかについて、著者は慎重なアプローチを提案しています。特に、既存のリソースとの衝突を避けるため、インポート時に新しい識別子を生成することを推奨しています。
失敗とリトライの処理: インポートとエクスポート操作の失敗とリトライについて、著者は詳細なガイダンスを提供しています。特に、インポート操作のリトライ時に重複リソースが作成されないよう、importRequestIdの使用を提案しています。

これらの原則を適用した、Rustでのインポート/エクスポート機能の実装例を以下に示します。

use uuid::Uuid;

pub struct ImportExportService {
    // サービスの依存関係
}

impl ImportExportService {
    pub async fn export_resources(&self, req: &ExportRequest) -> Result<Operation, Error> {
        let op = Operation {
            id: format!("operations/export_{}", Uuid::new_v4()),
            done: false,
            result: None,
            error: None,
            metadata: None,
        };

        let req_clone = req.clone();
        let op_clone = op.clone();
        tokio::spawn(async move {
            Self::run_export(&req_clone, op_clone).await;
        });

        Ok(op)
    }

    async fn run_export(req: &ExportRequest, op: Operation) {
        // エクスポートロジックの実装
        // 1. リソースの取得
        // 2. データの変換（OutputConfigに基づく）
        // 3. 外部ストレージへの書き込み（DataDestinationに基づく）
        // 4. 進捗の更新
    }

    pub async fn import_resources(&self, req: &ImportRequest) -> Result<Operation, Error> {
        let op = Operation {
            id: format!("operations/import_{}", Uuid::new_v4()),
            done: false,
            result: None,
            error: None,
            metadata: None,
        };

        let req_clone = req.clone();
        let op_clone = op.clone();
        tokio::spawn(async move {
            Self::run_import(&req_clone, op_clone).await;
        });

        Ok(op)
    }

    async fn run_import(req: &ImportRequest, op: Operation) {
        // インポートロジックの実装
        // 1. 外部ストレージからのデータ読み取り（DataSourceに基づく）
        // 2. データの変換（InputConfigに基づく）
        // 3. リソースの作成（importRequestIdを使用して重複を防ぐ）
        // 4. 進捗の更新
    }
}

この実装例では、インポートとエクスポート操作を非同期で実行し、LROを通じて進捗を追跡できるようにしています。また、データの転送と変換を分離し、柔軟性を確保しています。

インポートとエクスポートの影響とトレードオフ

著者は、インポート/エクスポート機能の導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

パフォーマンスとスケーラビリティ: APIサーバーが直接外部ストレージとやり取りすることで、データ転送の効率が大幅に向上します。しかし、これはAPIサーバーの負荷を増加させる可能性があります。
一貫性と可用性のバランス: エクスポート中のデータ一貫性を保証することは難しく、「スメア」が発生する可能性があります。完全な一貫性を求めると、システムの可用性が低下する可能性があります。
セキュリティの考慮: APIサーバーが外部ストレージに直接アクセスすることで、新たなセキュリティ上の課題が生じる可能性があります。適切なアクセス制御と認証メカニズムが不可欠です。
運用の複雑さ: インポート/エクスポート機能の導入により、システムの運用が複雑になる可能性があります。特に、失敗したオぺレーションの処理とリカバリーには注意が必要です。
バックアップ/リストアとの違い: 著者は、インポート/エクスポート機能がバックアップ/リストア機能とは異なることを強調しています。この違いを理解し、適切に使い分けることが重要です。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの統合: インポート/エクスポート機能は、マイクロサービス間のデータ移動を最適化する上で重要な役割を果たします。各サービスが独自のインポート/エクスポート機能を持つことで、サービス間のデータ交換が効率化されます。
クラウドネイティブ環境での活用: クラウドストレージサービス（例：Amazon S3、Google Cloud Storage）との直接統合により、データの移動と処理を効率化できます。
大規模データ処理: ビッグデータ分析や機械学習のためのデータ準備において、効率的なインポート/エクスポート機能は不可欠です。
コンプライアンスとデータガバナンス: データのインポート/エクスポート操作をAPIレベルで制御することで、データの流れを一元管理し、コンプライアンス要件への対応を容易にします。
障害復旧とシステム移行: 適切に設計されたインポート/エクスポート機能は、災害復旧やシステム移行シナリオにおいても有用です。

結論

第23章「Importing and exporting」は、APIにおけるデータのインポートとエクスポートの重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの効率性、柔軟性、そして全体的なシステムアーキテクチャを大きく向上させる可能性があります。

インポート/エクスポート設計で考慮すべき点を挙げます。

インポート/エクスポート機能は、APIサーバーと外部ストレージ間の直接的なデータ移動を可能にし、効率を大幅に向上させます。
データの転送（DataSource/DataDestination）と変換（InputConfig/OutputConfig）を分離することで、システムの柔軟性と再利用性が向上します。
長時間実行操作（LRO）として実装することで、クライアントは非同期で操作の進行状況を追跡できます。
データの一貫性、識別子の扱い、失敗とリトライの処理には特別な注意が必要です。
インポート/エクスポート機能はバックアップ/リストア機能とは異なることを理解し、適切に使い分けることが重要です。

大規模なデータセットを扱う場合や、マイクロサービス環境では特に重要な機能です。

ただしこの機能の導入には慎重な検討も必要です。特に、セキュリティ、データの一貫性、システムの複雑性の増加などの側面で課題が生じる可能性があります。これらの課題に適切に対処するためには、システムの要件と制約を十分に理解し、適切な設計決定を行う必要があります。

最後に、インポート/エクスポート機能の設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単にデータ移動の効率を向上させるだけでなく、システム全体の柔軟性、スケーラビリティ、そして運用効率の向上にも大きく貢献します。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

この章の内容は、特に大規模で長期的に運用されるシステムの設計において重要です。適切に設計されたインポート/エクスポート機能は、システムの進化と拡張を容易にし、長期的な保守性を向上させます。API設計者とシステム設計者は、これらの原則を深く理解し、実践することで、より堅牢で効率的なシステムを構築することができるでしょう。

Part 6 Safety and security

最後のパートでは、APIの安全性とセキュリティに関する重要なトピックが扱われています。バージョニングと互換性の維持、ソフト削除、リクエストの重複排除、リクエストの検証、リソースのリビジョン管理、リクエストの再試行、リクエストの認証など、APIの信頼性と安全性を確保するための様々な手法が詳細に解説されています。これらの要素は、APIの長期的な運用と進化において重要です。

24 Versioning and compatibility

「API Design Patterns」の第24章「Versioning and compatibility」は、APIのバージョニングと互換性の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はバージョニングと互換性の管理が単なる技術的な詳細ではなく、APIの長期的な成功と進化に直接影響を与える重要な戦略的決定であることを明確に示しています。

バージョニングの必要性と互換性の概念

著者は、ソフトウェア開発、特にAPIの進化が避けられない現実から議論を始めています。新機能の追加、バグの修正、セキュリティの向上など、APIを変更する理由は常に存在します。しかし、APIはその公開性と厳格性ゆえに、変更が難しいという特性を持っています。この緊張関係を解決するための主要な手段として、著者はバージョニングを提案しています。

バージョニングの本質は、APIの変更を管理可能な形で導入し、既存のクライアントに影響を与えることなく新機能を提供することです。著者は、バージョニングの主な目的を「ユーザーに可能な限り多くの機能を提供しつつ、最小限の不便さで済ませること」と定義しています。この定義は、APIデザインにおける重要な指針となります。

互換性の概念についても詳細に説明されています。著者は、互換性を「2つの異なるコンポーネントが正常に通信できる能力」と定義しています。APIのコンテキストでは、これは主にクライアントとサーバー間の通信を指します。特に、後方互換性（新しいバージョンのAPIが古いクライアントコードと正常に動作する能力）が重要です。

この概念は、マイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。複数のサービスが互いに依存し合う環境では、一つのAPIの変更が全体のシステムに波及的な影響を与える可能性があります。適切なバージョニング戦略は、このような環境でのシステムの安定性と進化を両立させるために不可欠です。

後方互換性の定義

著者は、後方互換性の定義が単純ではないことを指摘しています。一見すると「既存のコードが壊れないこと」という定義で十分に思えますが、実際にはより複雑です。著者は、後方互換性の定義が「APIを利用するユーザーのプロファイルと期待」に大きく依存すると主張しています。

例えば、新しい機能の追加は通常後方互換性があると考えられますが、リソースが制限されているIoTデバイスのような環境では、新しいフィールドの追加でさえメモリオーバーフローを引き起こす可能性があります。また、バグ修正についても、それが既存のクライアントの動作に影響を与える可能性がある場合、後方互換性を損なう可能性があります。

著者は、以下のようなシナリオについて詳細に議論しています。

新機能の追加
バグ修正
法的要件による強制的な変更
パフォーマンスの最適化
基礎となるアルゴリズムや技術の変更
一般的な意味的変更

これらの各シナリオにおいて、変更が後方互換性を持つかどうかは、APIのユーザーベースの特性と期待に大きく依存します。例えば、金融機関向けのAPIと、スタートアップ向けのAPIでは、安定性と新機能に対する要求が大きく異なる可能性があります。

この議論は、APIデザインが単なる技術的な問題ではなく、ビジネス戦略と密接に関連していることを示しています。APIデザイナーは、技術的な側面だけでなく、ユーザーのニーズ、ビジネス目標、法的要件などを総合的に考慮してバージョニング戦略を決定する必要があります。

バージョニング戦略

著者は、いくつかの主要なバージョニング戦略について詳細に説明しています。

永続的安定性（Perpetual stability）: 各バージョンを永続的に安定させ、後方互換性のない変更は常に新しいバージョンで導入する戦略。
アジャイル不安定性（Agile instability）: アクティブなバージョンの「滑走窓」を維持し、定期的に古いバージョンを廃止する戦略。
セマンティックバージョニング（Semantic versioning）: メジャー、マイナー、パッチの3つの数字を使用して変更の性質を明確に示す戦略。

各戦略には、それぞれ長所と短所があります。例えば、永続的安定性は高い安定性を提供しますが、新機能の導入が遅くなる可能性があります。一方、アジャイル不安定性は新機能の迅速な導入を可能にしますが、クライアントに頻繁な更新を強いる可能性があります。セマンティックバージョニングは柔軟性と明確性を提供しますが、多数のバージョンの管理が必要になる可能性があります。

これらの戦略の選択は、APIのユースケース、ユーザーベース、開発リソース、ビジネス目標など、多くの要因に依存します。例えば、マイクロサービスアーキテクチャを採用している組織では、各サービスが独立してバージョニングを行う必要がありますが、全体的な一貫性も維持する必要があります。このような環境では、セマンティックバージョニングが適している可能性が高いです。

Rustのコンテキストでは、以下のようなバージョニング戦略の実装例が考えられます。

use std::collections::HashMap;
use thiserror::Error;

#[derive(Debug, Clone)]
pub struct ApiVersion {
    pub major: u32,
    pub minor: u32,
    pub patch: u32,
}

pub struct ApiClient {
    pub version: ApiVersion,
    // その他のクライアント設定
}

#[derive(Error, Debug)]
pub enum ApiError {
    #[error("unsupported API version: {0:?}")]
    UnsupportedVersion(ApiVersion),
}

impl ApiClient {
    pub async fn call(
        &self,
        endpoint: &str,
        params: HashMap<String, serde_json::Value>,
    ) -> Result<serde_json::Value, ApiError> {
        // バージョンに基づいてAPIコールを調整
        match self.version.major {
            1 => {
                // v1のロジック
                todo!()
            }
            2 => {
                // v2のロジック
                todo!()
            }
            _ => Err(ApiError::UnsupportedVersion(self.version.clone())),
        }
        // 実際のAPI呼び出しロジック
    }
}

このような実装により、クライアントは特定のAPIバージョンを指定して操作を行うことができ、サーバー側では各バージョンに応じた適切な処理を行うことができます。

バージョニングのトレードオフ

著者は、バージョニング戦略を選択する際の主要なトレードオフについて議論しています。

粒度 vs 単純性: より細かいバージョン管理は柔軟性を提供しますが、複雑さも増加します。
安定性 vs 新機能: 高い安定性を維持するか、新機能を迅速に導入するかのバランス。
満足度 vs 普遍性: 一部のユーザーを非常に満足させるか、より多くのユーザーに受け入れられる方針を取るか。

これらのトレードオフは、APIの設計と進化に大きな影響を与えます。例えば、高度に規制された産業向けのAPIでは、安定性と予測可能性が最も重要かもしれません。一方、急速に進化するテクノロジー分野では、新機能の迅速な導入が優先されるかもしれません。

運用の観点からは、これらのトレードオフは以下のような影響を持ちます。

インフラストラクチャの複雑さ: 多数のバージョンを同時にサポートする必要がある場合、インフラストラクチャの管理が複雑になります。
モニタリングと可観測性: 各バージョンの使用状況、パフォーマンス、エラーレートを個別に監視する必要があります。
デプロイメントの戦略: 新バージョンのロールアウトと古いバージョンの段階的な廃止をどのように管理するか。
ドキュメンテーションとサポート: 各バージョンのドキュメントを維持し、サポートを提供する必要があります。

結論

第24章「Versioning and compatibility」は、APIのバージョニングと互換性管理の重要性と、その適切な実装方法を明確に示しています。著者の提案する原則は、APIの長期的な成功と進化を確保する上で重要です。

バージョニング戦略を決める際の検討事項です。

バージョニングは、APIの進化を可能にしつつ、既存のクライアントへの影響を最小限に抑えるための重要なツールです。
後方互換性の定義は、APIのユーザーベースと彼らの期待に大きく依存します。
バージョニング戦略の選択には、粒度vs単純性、安定性vs新機能、満足度vs普遍性などのトレードオフがあります。
適切なバージョニング戦略は、APIの使用目的、ユーザーベース、開発リソース、ビジネス目標など、多くの要因を考慮して選択する必要があります。
バージョニングはAPIの設計だけでなく、インフラストラクチャ、運用、サポートなど、システム全体に影響を与えます。

マイクロサービスやクラウドネイティブ環境では、バージョニング戦略がシステム全体の安定性を左右します。

バージョニングと互換性の管理は技術的な問題であると同時に、戦略的な決定でもあります。API設計者は、技術的な側面だけでなく、ビジネス目標、ユーザーのニーズ、法的要件、運用上の制約など、多くの要因を考慮してバージョニング戦略を決定する必要があります。適切に実装されたバージョニング戦略は、APIの長期的な成功と、それに依存するシステム全体の安定性と進化可能性を確保する重要な基盤となります。

最後に、バージョニングと互換性の管理は継続的なプロセスであることを認識することが重要です。技術の進化、ユーザーのニーズの変化、新たな法的要件の出現などに応じて、バージョニング戦略を定期的に見直し、必要に応じて調整することが求められます。この継続的な管理と適応が、APIの長期的な成功と、それに依存するシステム全体の健全性を確保する鍵となります。

25 Soft deletion

「API Design Patterns」の第25章「Soft deletion」は、APIにおけるソフト削除の概念、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はソフト削除が単なるデータ管理の手法ではなく、APIの柔軟性、データの保全性、そして全体的なシステムの運用性にどのように影響を与えるかを明確に示しています。

ソフト削除の動機と概要

著者は、ソフト削除の必要性から議論を始めています。従来のハード削除（データの完全な削除）には、誤って削除されたデータを復元できないという重大な欠点があります。著者は、この問題に対する解決策としてソフト削除を提案しています。ソフト削除は、データを実際に削除せず、「削除された」とマークすることで、必要に応じて後で復元できるようにする手法です。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、複数のサービスが相互に依存し合う環境では、一つのサービスでデータが誤って削除されると、システム全体に波及的な影響を与える可能性があります。ソフト削除を適切に実装することで、このようなリスクを軽減し、システムの回復力を高めることができます。

著者は、ソフト削除の基本的な実装として、リソースに deleted フラグを追加することを提案しています。このフラグにより、リソースが削除されたかどうかを示すことができます。さらに、expireTime フィールドを追加することで、ソフト削除されたリソースの自動的な完全削除（ハード削除）のスケジューリングも可能になります。

ソフト削除の実装

著者は、ソフト削除の実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

標準メソッドの修正: 標準的なCRUD操作、特に削除（Delete）操作を修正し、ソフト削除をサポートする必要があります。
リスト操作の調整: 標準的なリスト操作では、デフォルトでソフト削除されたリソースを除外し、オプションでそれらを含める機能を提供します。
アンデリート操作: ソフト削除されたリソースを復元するための新しいカスタムメソッドを導入します。
完全削除（Expunge）操作: ソフト削除されたリソースを完全に削除するための新しいカスタムメソッドを導入します。
有効期限の管理: ソフト削除されたリソースの自動的な完全削除をスケジュールするための仕組みを実装します。

これらの原則を適用した、Rustでのソフト削除の実装例を以下に示します。

use async_trait::async_trait;
use chrono::{DateTime, Duration, Utc};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Resource {
    pub id: String,
    pub name: String,
    pub deleted: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub expire_time: Option<DateTime<Utc>>,
}

#[async_trait]
pub trait ResourceService {
    async fn get(&self, id: &str) -> Result<Resource, Error>;
    async fn list(&self, include_deleted: bool) -> Result<Vec<Resource>, Error>;
    async fn delete(&self, id: &str) -> Result<(), Error>;
    async fn undelete(&self, id: &str) -> Result<(), Error>;
    async fn expunge(&self, id: &str) -> Result<(), Error>;
}

impl ResourceServiceImpl {
    pub async fn delete(&self, id: &str) -> Result<(), Error> {
        let mut resource = self.get(id).await?;
        resource.deleted = true;
        resource.expire_time = Some(Utc::now() + Duration::days(30)); // 30日後に自動削除
        self.update(&resource).await
    }

    pub async fn list(&self, include_deleted: bool) -> Result<Vec<Resource>, Error> {
        let resources = self.get_all().await?;
        if !include_deleted {
            Ok(resources.into_iter().filter(|r| !r.deleted).collect())
        } else {
            Ok(resources)
        }
    }
}

この実装例では、Resource 構造体に deleted フラグと expire_time フィールドを追加し、delete メソッドでソフト削除を実装しています。また、list メソッドでは include_deleted パラメータを使用して、ソフト削除されたリソースを含めるかどうかを制御しています。

ソフト削除の影響とトレードオフ

著者は、ソフト削除の導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

データストレージの増加: ソフト削除されたリソースはデータベースに残り続けるため、ストレージの使用量が増加します。これは、大規模なシステムでは無視できない問題となる可能性があります。
パフォーマンスへの影響: ソフト削除されたリソースを除外するための追加的なフィルタリングが必要となるため、特にリスト操作のパフォーマンスに影響を与える可能性があります。
複雑性の増加: ソフト削除を導入することで、APIの複雑性が増加します。これは、開発者の学習曲線を急にし、バグの可能性を増やす可能性があります。
データの整合性: ソフト削除されたリソースへの参照をどのように扱うかという問題があります。これは、特に複雑な関係性を持つリソース間で重要な課題となります。
セキュリティとプライバシー: ソフト削除されたデータが予想以上に長く保持される可能性があり、これはデータ保護規制（例：GDPR）との関連で課題となる可能性があります。

これらのトレードオフを適切に管理することが、ソフト削除の成功的な実装の鍵となります。例えば、ストレージとパフォーマンスの問題に対しては、定期的なクリーンアップジョブを実装し、長期間ソフト削除状態にあるリソースを自動的に完全削除することが考えられます。また、データの整合性の問題に対しては、関連リソースの削除ポリシーを慎重に設計し、カスケード削除やリファレンスの無効化などの戦略を適切に選択する必要があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

マイクロサービスアーキテクチャとの統合: ソフト削除は、マイクロサービス間のデータ整合性を維持する上で重要な役割を果たします。例えば、あるサービスでソフト削除されたリソースが、他のサービスではまだ参照されている可能性があります。このような場合、ソフト削除により、サービス間の整合性を保ちつつ、必要に応じてデータを復元することが可能になります。
イベント駆動アーキテクチャとの連携: ソフト削除、アンデリート、完全削除などの操作をイベントとして発行することで、関連するシステムコンポーネントが適切に反応し、全体的な一貫性を維持することができます。
データガバナンスとコンプライアンス: ソフト削除は、データ保持ポリシーやデータ保護規制への対応を容易にします。例えば、ユーザーデータの「忘れられる権利」（GDPR）に対応する際、ソフト削除を活用することで、データを即座に利用不可能にしつつ、法的要件に基づいて一定期間保持することが可能になります。
監査とトレーサビリティ: ソフト削除を実装することで、リソースのライフサイクル全体を追跡することが容易になります。これは、システムの変更履歴を把握し、問題が発生した場合のトラブルシューティングを容易にします。
バックアップと災害復旧: ソフト削除は、誤って削除されたデータの復旧を容易にします。これは、特に重要なビジネスデータを扱うシステムにおいて、データ損失のリスクを大幅に軽減します。
パフォーマンス最適化: ソフト削除の実装には、適切なインデックス戦略が不可欠です。例えば、deleted フラグにインデックスを作成することで、非削除リソースの検索パフォーマンスを維持することができます。
ストレージ管理: ソフト削除されたリソースの自動的な完全削除（エクスパイア）を実装することで、ストレージ使用量を管理しつつ、一定期間のデータ復元可能性を確保できます。これは、コストとデータ保護のバランスを取る上で重要です。

ソフト削除とシステムアーキテクチャ

ソフト削除の設計は、システム全体のアーキテクチャに大きな影響を与えます。以下の点について考慮する必要があります。

データモデルとスキーマ設計: ソフト削除をサポートするために、全てのリソースに deleted フラグと expireTime フィールドを追加する必要があります。これは、データベーススキーマの設計に影響を与えます。
クエリパフォーマンス: ソフト削除されたリソースを除外するために、ほとんどのクエリに追加の条件が必要になります。これは、特に大規模なデータセットでパフォーマンスに影響を与える可能性があります。適切なインデックス戦略が重要になります。
バージョニングと互換性: ソフト削除の導入は、APIの大きな変更となる可能性があります。既存のクライアントとの互換性を維持しつつ、この機能をどのように導入するかを慎重に検討する必要があります。
キャッシュ戦略: ソフト削除されたリソースのキャッシュ管理は複雑になる可能性があります。キャッシュの無効化戦略を適切に設計する必要があります。
イベントソーシングとCQRS: ソフト削除は、イベントソーシングやCQRS（Command Query Responsibility Segregation）パターンと組み合わせることで、より強力になります。削除イベントを記録し、読み取りモデルを適切に更新することで、システムの柔軟性と一貫性を向上させることができます。

結論

第25章「Soft deletion」は、APIにおけるソフト削除の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性、データの保全性、そして全体的なシステムの運用性を大きく向上させる可能性があります。

ソフト削除実装の要点を5つにまとめます。

ソフト削除は、データの誤削除からの保護と復元可能性を提供する重要な機能です。
標準的なCRUD操作、特に削除とリスト操作を適切に修正する必要があります。
アンデリートと完全削除（Expunge）のための新しいカスタムメソッドが必要です。
ソフト削除されたリソースの自動的な完全削除（エクスパイア）を管理するメカニズムが重要です。
ソフト削除の導入には、ストレージ使用量の増加、パフォーマンスへの影響、複雑性の増加などのトレードオフがあります。

データの重要性が高いシステムや、複雑なデータ関係を持つシステムでは、ソフト削除の実装が特に重要です。

ただしソフト削除の導入には慎重な検討も必要です。特に、パフォーマンス、ストレージ使用量、データの整合性、セキュリティとプライバシーの観点から、システムの要件と制約を十分に理解し、適切な設計決定を行う必要があります。

最後に、ソフト削除の設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単にデータの削除方法を変更するだけでなく、システム全体のデータライフサイクル管理、バックアップと復旧戦略、コンプライアンス対応、そして運用効率の向上にも大きく貢献します。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

ソフト削除の適切な実装は、システムの回復力を高め、データ管理の柔軟性を向上させます。API設計者とシステム設計者は、これらの原則を深く理解し、実践することで、より堅牢で信頼性の高いシステムを構築することができるでしょう。

26 Request deduplication

「API Design Patterns」の第26章「Request deduplication」は、APIにおけるリクエストの重複排除の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はリクエストの重複排除が単なる最適化ではなく、APIの信頼性、一貫性、そして全体的なシステムの堅牢性にどのように影響を与えるかを明確に示しています。

リクエスト重複排除の必要性と概要

著者は、ネットワークの不確実性から議論を始めています。現代のシステム、特にクラウドネイティブな環境やモバイルアプリケーションにおいて、ネットワークの信頼性は常に課題となります。リクエストが失敗した場合、クライアントは通常リトライを行いますが、これが意図しない副作用を引き起こす可能性があります。特に非べき等なメソッド（例えば、リソースの作成や更新）では、同じ操作が複数回実行されることで、データの整合性が損なわれる可能性があります。

この問題に対処するため、著者はリクエスト識別子（request identifier）の使用を提案しています。これは、クライアントが生成する一意の識別子で、APIサーバーはこの識別子を使用して重複リクエストを検出し、適切に処理します。

この概念は、マイクロサービスアーキテクチャにおいて特に重要です。複数のサービスが協調して動作する環境では、一つのリクエストの失敗が連鎖的な影響を及ぼす可能性があります。リクエストの重複排除を適切に実装することで、システム全体の一貫性と信頼性を向上させることができます。

著者は、リクエスト重複排除の基本的な流れを以下のように提案しています。

クライアントがリクエスト識別子を含むリクエストを送信する。
サーバーは識別子をチェックし、以前に処理されたかどうかを確認する。
新しいリクエストの場合は通常通り処理し、結果をキャッシュする。
重複リクエストの場合は、キャッシュされた結果を返す。

この方法により、ネットワークの不確実性に起因する問題を軽減しつつ、クライアントに一貫した応答を提供することができます。

リクエスト重複排除の実装

著者は、リクエスト重複排除の実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

リクエスト識別子: クライアントが生成する一意の文字列。これは通常、UUIDやその他のランダムな文字列が使用されます。
レスポンスのキャッシング: 処理されたリクエストの結果をキャッシュし、同じ識別子で再度リクエストがあった場合に使用します。
一貫性の維持: キャッシュされた応答は、その後のデータの変更に関わらず、元のリクエスト時点の状態を反映する必要があります。
衝突の管理: リクエスト識別子の衝突（異なるリクエストに同じ識別子が使用される場合）に対処するため、リクエストの内容も併せてチェックする必要があります。
キャッシュの有効期限: キャッシュされた応答に適切な有効期限を設定し、メモリ使用量を管理します。

これらの原則を適用した、Rustでのリクエスト重複排除の実装例を以下に示します。

use chrono::{DateTime, Duration, Utc};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use sha2::{Digest, Sha256};
use std::collections::HashMap;
use std::sync::RwLock;
use thiserror::Error;

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct RequestWithId {
    pub request_id: String,
    pub payload: Value,
}

pub struct ResponseCache {
    cache: RwLock<HashMap<String, CachedResponse>>,
}

struct CachedResponse {
    response: Value,
    content_hash: String,
    expire_time: DateTime<Utc>,
}

#[derive(Debug, Error)]
pub enum CacheError {
    #[error("request ID collision detected")]
    IdCollision,
    #[error("processing error: {0}")]
    ProcessingError(String),
}

impl ResponseCache {
    pub fn new() -> Self {
        Self {
            cache: RwLock::new(HashMap::new()),
        }
    }

    pub fn process<F>(&self, req: RequestWithId, processor: F) -> Result<Value, CacheError>
    where
        F: FnOnce(Value) -> Result<Value, String>,
    {
        {
            let cache = self.cache.read().expect("lock poisoned");
            if let Some(cached) = cache.get(&req.request_id) {
                let content_hash = calculate_hash(&req.payload);
                if content_hash != cached.content_hash {
                    return Err(CacheError::IdCollision);
                }
                return Ok(cached.response.clone());
            }
        }

        let response = processor(req.payload.clone())
            .map_err(CacheError::ProcessingError)?;

        {
            let mut cache = self.cache.write().expect("lock poisoned");
            cache.insert(
                req.request_id,
                CachedResponse {
                    response: response.clone(),
                    content_hash: calculate_hash(&req.payload),
                    expire_time: Utc::now() + Duration::minutes(5),
                },
            );
        }

        Ok(response)
    }
}

fn calculate_hash(payload: &Value) -> String {
    let mut hasher = Sha256::new();
    hasher.update(payload.to_string().as_bytes());
    format!("{:x}", hasher.finalize())
}

この実装例では、リクエスト識別子とペイロードを含むRequestWithId構造体を定義し、ResponseCache構造体でキャッシュを管理しています。processメソッドは、重複チェック、キャッシュの取得または更新、そして実際の処理を行います。また、リクエスト識別子の衝突を検出するため、ペイロードのハッシュも併せて保存しています。

リクエスト重複排除の影響とトレードオフ

著者は、リクエスト重複排除の導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

メモリ使用量: キャッシュの導入により、メモリ使用量が増加します。適切なキャッシュ有効期限の設定が重要です。
一貫性と鮮度のバランス: キャッシュされた応答は、最新のデータ状態を反映していない可能性があります。これは、クライアントの期待と一致しない場合があります。
複雑性の増加: リクエスト重複排除の実装は、APIの複雑性を増加させます。これは、開発とデバッグの難しさを増す可能性があります。
パフォーマンスへの影響: キャッシュのチェックと管理にはオーバーヘッドがありますが、重複リクエストの処理を回避することでパフォーマンスが向上する可能性もあります。
分散システムにおける課題: マイクロサービスアーキテクチャなどの分散システムでは、キャッシュの一貫性維持が複雑になります。

これらのトレードオフを適切に管理することが、リクエスト重複排除の成功的な実装の鍵となります。例えば、キャッシュのパフォーマンスと一貫性のバランスを取るために、キャッシュ戦略を慎重に設計する必要があります。また、分散キャッシュシステム（例：Redis）の使用を検討し、マイクロサービス間でキャッシュを共有することも有効な戦略です。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

耐障害性の向上: リクエスト重複排除は、ネットワークの一時的な障害やクライアントの予期せぬ動作に対するシステムの耐性を高めます。これは特に、金融取引や重要なデータ更新を扱うシステムで重要です。
イベント駆動アーキテクチャとの統合: リクエスト重複排除は、イベント駆動アーキテクチャにおいても重要です。例えば、メッセージキューを使用するシステムで、メッセージの重複処理を防ぐために同様の技術を適用できます。
グローバルユニーク識別子の生成: クライアント側でのユニークな識別子生成は、分散システムにおける重要な課題です。UUIDv4やULIDなどの効率的で衝突の可能性が低い識別子生成アルゴリズムの使用を検討すべきです。
監視とオブザーバビリティ: リクエスト重複排除の効果を測定し、システムの挙動を理解するために、適切な監視とロギングが不可欠です。重複リクエストの頻度、キャッシュヒット率、識別子の衝突回数などの指標を追跡することで、システムの健全性を評価できます。
セキュリティの考慮: リクエスト識別子の予測可能性や操作可能性に注意を払う必要があります。悪意のあるユーザーが識別子を推測または再利用することで、システムを悪用する可能性があります。
キャッシュ戦略の最適化: キャッシュのパフォーマンスと鮮度のバランスを取るために、階層的キャッシュやキャッシュの事前読み込みなどの高度な技術を検討することができます。
バージョニングとの統合: APIのバージョニング戦略とリクエスト重複排除メカニズムを統合する方法を考慮する必要があります。新しいバージョンのAPIで重複排除の実装が変更された場合、古いバージョンとの互換性をどのように維持するかを検討しなければなりません。

リクエスト重複排除とシステムアーキテクチャ

リクエスト重複排除の設計は、システム全体のアーキテクチャに大きな影響を与えます。以下の点について考慮する必要があります。

分散キャッシュシステム: マイクロサービスアーキテクチャにおいては、中央集権的なキャッシュシステム（例：Redis）の使用を検討する必要があります。これにより、異なるサービス間でキャッシュ情報を共有し、システム全体の一貫性を維持できます。
非同期処理との統合: 長時間実行される操作や非同期処理を含むシステムでは、リクエスト重複排除メカニズムをより慎重に設計する必要があります。例えば、処理の開始時点でキャッシュエントリを作成し、処理の完了時に更新するなどの戦略が考えられます。
フォールバック戦略: キャッシュシステムの障害に備えて、適切なフォールバック戦略を実装する必要があります。例えば、キャッシュが利用できない場合は、一時的に重複排除を無効にし、代わりにべき等性を保証する他の方法を使用するなどです。
キャッシュの整合性維持: 分散システムにおいては、キャッシュの整合性を維持することが課題となります。イベントソーシングやCQRSなどのパターンを使用して、キャッシュの更新と実際のデータ更新を同期させる方法を検討する必要があります。
スケーラビリティの考慮: リクエスト重複排除メカニズムがシステムのスケーラビリティのボトルネックにならないよう注意が必要です。負荷分散されたシステムでは、キャッシュの分散や複製を適切に設計する必要があります。

結論

第26章「Request deduplication」は、APIにおけるリクエスト重複排除の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの信頼性、一貫性、そして全体的なシステムの堅牢性を大きく向上させる可能性があります。

リクエスト重複排除を実装する際のポイントです。

リクエスト重複排除は、ネットワークの不確実性に起因する問題を軽減し、非べき等な操作の安全性を向上させる重要なメカニズムです。
クライアント生成のユニークな識別子と、サーバー側でのレスポンスキャッシングが、この実装の核心となります。
キャッシュの一貫性、識別子の衝突管理、適切なキャッシュ有効期限の設定が、実装上の重要な考慮点となります。
リクエスト重複排除の導入には、メモリ使用量の増加、複雑性の増加、一貫性と鮮度のバランスなどのトレードオフがあります。
分散システムやマイクロサービスアーキテクチャにおいては、キャッシュの一貫性維持と分散が特に重要な課題となります。

ネットワークの信頼性が低い環境や、重要なデータ更新を扱うシステムでは特に重要な機能です。

ただしリクエスト重複排除の導入には慎重な検討も必要です。特に、パフォーマンス、メモリ使用量、システムの複雑性の増加、セキュリティの観点から、システムの要件と制約を十分に理解し、適切な設計決定を行う必要があります。

最後に、リクエスト重複排除の設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単に個々のリクエストの重複を防ぐだけでなく、システム全体の信頼性、スケーラビリティ、そして運用効率の向上にも大きく貢献します。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

リクエスト重複排除の適切な実装は、システムの回復力を高め、データの整合性を保護し、ユーザー体験を向上させる可能性があります。特に、マイクロサービスアーキテクチャやクラウドネイティブな環境では、この機能の重要性がより顕著になります。API設計者とシステム設計者は、これらの原則を深く理解し、実践することで、より堅牢で信頼性の高いシステムを構築することができるでしょう。

さらに、リクエスト重複排除メカニズムは、システムの可観測性と運用性の向上にも貢献します。適切に実装されたリクエスト重複排除システムは、重複リクエストの頻度、パターン、原因に関する貴重な洞察を提供し、システムの挙動やネットワークの信頼性に関する問題を早期に検出することを可能にします。これらの情報は、システムの最適化や問題のトラブルシューティングに有用です。

最後に、リクエスト重複排除の実装は、APIの設計哲学と密接に関連しています。これはクライアントとサーバーの責任分担、エラー処理戦略、リトライポリシーなど、APIの基本的な設計原則に影響を与えます。したがって、リクエスト重複排除メカニズムの導入を検討する際は、APIの全体的な設計哲学との整合性を慎重に評価し、必要に応じて調整を行うことが重要です。

このような包括的なアプローチを取ることで、リクエスト重複排除は単なる技術的な解決策を超え、システム全体の品質と信頼性を向上させる重要な要素となります。API設計者とシステムアーキテクトは、この機能の重要性を認識し、適切に実装することで、より堅牢で効率的、そして信頼性の高いシステムを構築することができるでしょう。

27 Request validation

「API Design Patterns」の第27章「Request validation」は、APIにおけるリクエスト検証の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はリクエスト検証が単なる便利機能ではなく、APIの安全性、信頼性、そして全体的なユーザー体験にどのように影響を与えるかを明確に示しています。

リクエスト検証の必要性と概要

著者は、APIの複雑さとそれに伴う誤用のリスクから議論を始めています。最も単純に見えるAPIでさえ、その内部動作は複雑であり、ユーザーが意図した通りに動作するかどうかを事前に確認することは困難です。特に、本番環境で未検証のリクエストを実行することのリスクは高く、著者はこれを車の修理に例えています。素人が車をいじることで深刻な問題を引き起こす可能性があるのと同様に、未検証のAPIリクエストは本番システムに予期せぬ影響を与える可能性があります。

この問題に対処するため、著者はvalidateOnlyフィールドの導入を提案しています。これは、リクエストを実際に実行せずに検証のみを行うためのフラグです。この機能により、ユーザーは安全にリクエストの結果をプレビューし、潜在的な問題を事前に把握することができます。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。複数のサービスが相互に依存し合う複雑なシステムでは、一つの誤ったリクエストが連鎖的に問題を引き起こす可能性があります。リクエスト検証を適切に実装することで、このようなリスクを大幅に軽減し、システム全体の安定性と信頼性を向上させることができます。

著者は、リクエスト検証の基本的な流れを以下のように提案しています。

クライアントがvalidateOnly: trueフラグを含むリクエストを送信する。
サーバーはリクエストを通常通り処理するが、実際のデータ変更や副作用を伴う操作は行わない。
サーバーは、実際のリクエストが行われた場合と同様のレスポンスを生成し、返却する。

この方法により、ユーザーは安全にリクエストの結果をプレビューし、潜在的な問題（権限不足、データの不整合など）を事前に把握することができます。

リクエスト検証の実装

著者は、リクエスト検証の実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

validateOnlyフラグ: リクエストオブジェクトにオプションのブーリアンフィールドとして追加します。デフォルトはfalseであるべきです。
検証の範囲: 可能な限り多くの検証を行うべきです。これには、権限チェック、データの整合性チェック、参照整合性チェックなどが含まれます。
外部依存関係の扱い: 外部サービスとの通信が必要な場合、それらのサービスが検証モードをサポートしていない限り、その部分の検証は省略する必要があります。
レスポンスの生成: 実際のリクエストと同様のレスポンスを生成すべきです。ただし、サーバー生成の識別子などの一部のフィールドは空白または仮の値で埋める必要があります。
安全性とべき等性: 検証リクエストは常に安全（データを変更しない）かつべき等（同じリクエストで常に同じ結果を返す）であるべきです。

これらの原則を適用した、Rustでのリクエスト検証の実装例を以下に示します。

use serde::{Deserialize, Serialize};
use thiserror::Error;

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CreateChatRoomRequest {
    pub resource: ChatRoom,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub validate_only: bool,
}

#[derive(Debug, Error)]
pub enum ServiceError {
    #[error("permission denied: {0}")]
    PermissionDenied(String),
    #[error("validation error: {0}")]
    ValidationError(String),
}

impl Service {
    pub async fn create_chat_room(
        &self,
        req: CreateChatRoomRequest,
    ) -> Result<ChatRoom, ServiceError> {
        self.validate_create_chat_room(&req).await?;

        if req.validate_only {
            return Ok(ChatRoom {
                id: "placeholder-id".to_string(),
                name: req.resource.name,
                // その他のフィールド
                ..Default::default()
            });
        }

        // 実際のリソース作成ロジック
        self.actually_create_chat_room(req.resource).await
    }

    async fn validate_create_chat_room(
        &self,
        req: &CreateChatRoomRequest,
    ) -> Result<(), ServiceError> {
        // 権限チェック
        self.check_permissions("create_chat_room").await?;

        // データ検証
        validate_chat_room_data(&req.resource)?;

        // 外部依存関係のチェック（可能な場合）
        // ...

        Ok(())
    }
}

fn validate_chat_room_data(chat_room: &ChatRoom) -> Result<(), ServiceError> {
    if chat_room.name.is_empty() {
        return Err(ServiceError::ValidationError("name is required".to_string()));
    }
    Ok(())
}

この実装例では、validate_onlyフラグに基づいて実際の処理を行うかどうかを制御しています。検証フェーズは常に実行され、エラーがある場合は早期に返却されます。検証モードの場合、実際のリソース作成は行わず、プレースホルダーのレスポンスを返します。

リクエスト検証の影響とトレードオフ

著者は、リクエスト検証の導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

複雑性の増加: リクエスト検証機能の追加は、APIの複雑性を増加させます。これは、実装とテストの負担を増やす可能性があります。
パフォーマンスへの影響: 検証リクエストは、実際の処理を行わないため一般的に高速ですが、大量の検証リクエストがあった場合、システムに負荷をかける可能性があります。
外部依存関係の扱い: 外部サービスとの連携が必要な場合、完全な検証が難しくなる可能性があります。これは、システムの一部の動作を正確に予測できなくなることを意味します。
不確定な結果の扱い: ランダム性や時間依存の処理を含むリクエストの検証は、実際の結果を正確に予測することが難しい場合があります。

これらのトレードオフを適切に管理することが、リクエスト検証の成功的な実装の鍵となります。例えば、外部依存関係の扱いについては、モックやスタブを使用して可能な限り現実的な検証を行うことが考えられます。また、不確定な結果については、可能な結果の範囲を示すなど、ユーザーに適切な情報を提供することが重要です。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

リスク管理とコスト削減: リクエスト検証は、本番環境での不適切なリクエストによるリスクを大幅に軽減します。これは、特に金融系のAPIや重要なデータを扱うシステムで重要です。
開発効率の向上: 開発者がAPIの動作を事前に確認できることで、開発サイクルが短縮され、品質が向上します。これは、特に複雑なマイクロサービス環境で重要です。
ドキュメンテーションの補完: リクエスト検証は、動的なドキュメンテーションの一形態と見なすこともできます。開発者は、APIの動作を実際に試すことで、ドキュメントだけでは分かりにくい細かな挙動を理解できます。
セキュリティの強化: 検証モードを使用することで、潜在的な脆弱性や不適切なアクセス試行を事前に発見できる可能性があります。これは、セキュリティ監査の一部として活用できます。
運用の簡素化: 本番環境での問題を事前に回避できることで、インシデント対応の頻度が減少し、運用負荷が軽減されます。
段階的なデプロイメント戦略との統合: 新機能のロールアウト時に、検証モードを活用して潜在的な問題を早期に発見することができます。これは、カナリアリリースやブルー/グリーンデプロイメントなどの戦略と組み合わせて効果的です。

リクエスト検証とシステムアーキテクチャ

リクエスト検証の設計は、システム全体のアーキテクチャに大きな影響を与えます。以下の点について考慮する必要があります。

マイクロサービスアーキテクチャでの実装: 複数のサービスにまたがるリクエストの検証は、特に注意が必要です。サービス間の依存関係を考慮し、整合性のある検証結果を提供する必要があります。
キャッシュ戦略: 検証リクエストの結果をキャッシュすることで、パフォーマンスを向上させることができます。ただし、キャッシュの有効期限や更新戦略を慎重に設計する必要があります。
非同期処理との統合: 長時間実行される操作や非同期処理を含むシステムでは、検証モードの動作を慎重に設計する必要があります。例えば、非同期処理の予測される結果をシミュレートする方法を考える必要があります。
モニタリングと可観測性: 検証リクエストの使用パターンや頻度を監視することで、APIの使用状況や潜在的な問題をより深く理解できます。これらの指標は、システムの最適化やユーザビリティの向上に活用できます。
テスト戦略: リクエスト検証機能自体もテストの対象となります。特に、実際の処理と検証モードの結果の一貫性を確保するためのテスト戦略が重要です。

結論

第27章「Request validation」は、APIにおけるリクエスト検証の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの安全性、信頼性、そして全体的なユーザー体験を大きく向上させる可能性があります。

validateOnly機能を導入する際の設計指針です。

リクエスト検証は、APIの複雑さに起因するリスクを軽減する重要なメカニズムです。
validateOnlyフラグを使用することで、ユーザーは安全にリクエストの結果をプレビューできます。
検証リクエストは、可能な限り実際のリクエストと同様の処理を行いますが、データの変更や副作用を伴う操作は避けるべきです。
外部依存関係や不確定な結果を含むリクエストの検証には特別な配慮が必要です。
リクエスト検証の導入には、複雑性の増加やパフォーマンスへの影響などのトレードオフがありますが、それらを上回る価値を提供する可能性があります。

重要なデータを扱うシステムやマイクロサービス環境では、この機能の実装が特に重要です。

ただしリクエスト検証の導入には慎重な検討も必要です。特に、パフォーマンス、複雑性の管理、外部依存関係の扱いなどの観点から、システムの要件と制約を十分に理解し、適切な設計決定を行う必要があります。

最後に、リクエスト検証の設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単に個々のリクエストの安全性を向上させるだけでなく、システム全体の信頼性、運用効率、そして開発生産性の向上にも大きく貢献します。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

リクエスト検証の適切な実装は、システムの回復力を高め、開発サイクルを短縮し、ユーザー体験を向上させる可能性があります。API設計者とシステム設計者は、これらの原則を深く理解し、実践することで、より堅牢で使いやすいシステムを構築することができるでしょう。特に、急速に変化するビジネス要件や複雑な技術スタックを持つ現代のソフトウェア開発環境において、リクエスト検証は重要な役割を果たす可能性があります。

最後に、リクエスト検証は単なる技術的な機能ではなく、APIの設計哲学を反映するものでもあります。これは、ユーザーフレンドリーなインターフェース、透明性、そして予測可能性への commitment を示しています。適切に実装されたリクエスト検証機能は、API提供者とその消費者の間の信頼関係を強化し、より効果的なコラボレーションを促進します。

この機能は、「フェイルファスト」の原則とも整合しており、問題を早期に発見し、修正するための強力なツールとなります。開発者は、本番環境に変更をデプロイする前に、その影響を安全に評価することができます。これにより、イテレーションのサイクルが短縮され、イノベーションのペースが加速する可能性があります。

また、リクエスト検証は、APIのバージョニングや進化の戦略とも密接に関連しています。新しいバージョンのAPIをリリースする際、開発者は検証モードを使用して、既存のクライアントへの影響を事前に評価することができます。これにより、破壊的な変更のリスクを最小限に抑えつつ、APIを継続的に改善することが可能になります。

さらに、この機能は、APIの教育的側面も持っています。開発者は、検証モードを通じてAPIの動作を実験的に学ぶことができ、これがドキュメントを補完する動的な学習ツールとなります。これは、API の採用を促進し、正しい使用法を奨励することにつながります。

最終的に、リクエスト検証の実装は、API設計者がユーザーの視点に立ち、その経験を常に考慮していることを示す象徴的な機能と言えるでしょう。これは、単に機能を提供するだけでなく、ユーザーの成功を積極的に支援するという、より広範なAPI設計哲学の一部となります。

このような包括的なアプローチを取ることで、リクエスト検証は単なる技術的機能を超え、APIの品質、信頼性、そして全体的な価値を大きく向上させる重要な要素となります。API設計者とシステムアーキテクトは、この機能の重要性を認識し、適切に実装することで、より使いやすく、信頼性が高く、そして継続的な進化が可能なAPIを構築することができるでしょう。これは、急速に変化し、常に新しい課題が生まれる現代のソフトウェア開発環境において、特に重要な価値となります。

28 Resource revisions

「API Design Patterns」の第28章「Resource revisions」は、APIにおけるリソースのリビジョン管理の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はリソースリビジョンが単なる機能の追加ではなく、APIの柔軟性、データの整合性、そして全体的なシステムの運用性にどのように影響を与えるかを明確に示しています。

この章では、リソースの変更履歴を安全に保存し、過去の状態を取得または復元する方法について説明しています。具体的には、個々のリビジョンの識別方法、リビジョンの作成戦略（暗黙的または明示的）、利用可能なリビジョンのリスト化と特定のリビジョンの取得方法、以前のリビジョンへの復元の仕組み、そしてリビジョン可能なリソースの子リソースの扱い方について詳しく解説しています。

リソースリビジョンの必要性と概要

著者は、リソースリビジョンの必要性から議論を始めています。多くのAPIでは、リソースの現在の状態のみを保持し、過去の変更履歴を無視しています。しかし、契約書、購買注文書、法的文書、広告キャンペーンなどのリソースでは、変更履歴を追跡する必要性が高くなります。これにより、問題が発生した際に、どの変更が原因であるかを特定しやすくなります。

リソースリビジョンの概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。例えば、複数のサービスが協調して動作する環境では、各サービスが管理するリソースの変更履歴を適切に追跡し、必要に応じて過去の状態を参照または復元できることが、システム全体の一貫性と信頼性を確保する上で重要になります。

著者は、リソースリビジョンの基本的な構造として、既存のリソースに2つの新しいフィールドを追加することを提案しています。

revisionId: リビジョンの一意の識別子
revisionCreateTime: リビジョンが作成された時刻

これらのフィールドを追加することで、リソースの複数のスナップショットを時系列で管理できるようになります。これにより、リソースの変更履歴を追跡し、必要に応じて過去の状態を参照または復元することが可能になります。

この概念を視覚的に表現するために、著者は以下のような図を提示しています。

Figure 28.1 Adding support for revisions to a Message resource

この図は、通常のMessageリソースにrevisionIdとrevisionCreateTimeフィールドを追加することで、リビジョン管理をサポートする方法を示しています。

リソースリビジョンの実装

著者は、リソースリビジョンの実装に関して詳細なガイダンスを提供しています。主なポイントは以下の通りです。

リビジョン識別子: リビジョンの一意性を確保するために、ランダムな識別子（例：UUID）を使用することを推奨しています。これにより、リビジョンの順序や時間に依存せずに、各リビジョンを一意に識別できます。
リビジョンの作成戦略: 著者は、暗黙的なリビジョン作成（リソースが変更されるたびに自動的に新しいリビジョンを作成）と明示的なリビジョン作成（ユーザーが明示的にリビジョンの作成を要求）の2つの戦略を提案しています。各アプローチにはそれぞれ長所と短所があり、システムの要件に応じて選択する必要があります。
リビジョンの取得と一覧表示: 特定のリビジョンを取得するためのメソッドと、利用可能なリビジョンを一覧表示するためのメソッドの実装について説明しています。これらのメソッドにより、ユーザーはリソースの変更履歴を参照し、必要に応じて特定の時点の状態を取得できます。
リビジョンの復元: 以前のリビジョンの状態にリソースを戻すための復元操作の実装方法を解説しています。この操作は、誤った変更を元に戻したり、特定の時点の状態に戻したりする際に重要です。
子リソースの扱い: リビジョン可能なリソースが子リソースを持つ場合の取り扱いについても議論しています。子リソースをリビジョンに含めるかどうかは、システムの要件やパフォーマンスの考慮事項に応じて決定する必要があります。

これらの原則を適用した、Rustでのリソースリビジョンの実装例を以下に示します。

use async_trait::async_trait;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use uuid::Uuid;

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Resource {
    pub id: String,
    pub content: String,
    pub revision_id: String,
    pub revision_create_time: DateTime<Utc>,
}

#[async_trait]
pub trait ResourceService {
    async fn get_resource(&self, id: &str, revision_id: &str) -> Result<Resource, Error>;
    async fn list_resource_revisions(&self, id: &str) -> Result<Vec<Resource>, Error>;
    async fn create_resource_revision(&self, id: &str) -> Result<Resource, Error>;
    async fn restore_resource_revision(&self, id: &str, revision_id: &str) -> Result<Resource, Error>;
}

impl ResourceServiceImpl {
    pub async fn create_resource_revision(&self, id: &str) -> Result<Resource, Error> {
        let resource = self.get_latest_resource(id).await?;

        let new_revision = Resource {
            id: resource.id,
            content: resource.content,
            revision_id: Uuid::new_v4().to_string(),
            revision_create_time: Utc::now(),
        };

        self.save_revision(&new_revision).await?;

        Ok(new_revision)
    }
}

この実装例では、Resource構造体にリビジョン関連のフィールドを追加し、ResourceServiceトレイトでリビジョン管理に関連するメソッドを定義しています。create_resource_revisionメソッドは、新しいリビジョンを作成し、保存する処理を示しています。

リソースリビジョンの影響とトレードオフ

著者は、リソースリビジョンの導入がシステム全体に与える影響とトレードオフについても詳細に論じています。

ストレージ使用量の増加: リビジョンを保存することで、ストレージの使用量が大幅に増加します。特に、頻繁に変更されるリソースや大規模なリソースの場合、この影響は無視できません。
パフォーマンスへの影響: リビジョンの作成や取得には追加のオーバーヘッドが発生します。特に、大量のリビジョンが存在する場合、リビジョンの一覧表示や特定のリビジョンの取得に時間がかかる可能性があります。
複雑性の増加: リビジョン管理機能の追加により、APIの複雑性が増加します。これは、開発者の学習曲線を急にし、バグの可能性を増やす可能性があります。
一貫性の課題: 特に分散システムにおいて、リビジョンの一貫性を維持することは難しい場合があります。例えば、複数のサービスにまたがるリソースの場合、全体的な一貫性を確保するのが困難になる可能性があります。
リビジョン管理のオーバーヘッド: リビジョンの保持期間、古いリビジョンの削除ポリシー、リビジョン数の制限など、追加的な管理タスクが発生します。

これらのトレードオフを適切に管理することが、リソースリビジョンの成功的な実装の鍵となります。例えば、ストレージ使用量の増加に対しては、圧縮技術の使用や、重要でないリビジョンの定期的な削除などの戦略が考えられます。パフォーマンスへの影響に関しては、効率的なインデックス設計や、必要に応じてキャッシュを活用することで軽減できる可能性があります。

実践的な応用と考察

この章の内容は、実際のAPI設計において重要です。特に、以下の点が重要になります。

監査とコンプライアンス: リソースリビジョンは、変更履歴の追跡が必要な規制環境（金融サービス、医療情報システムなど）で特に重要です。変更の誰が、いつ、何をしたかを正確に記録し、必要に応じて過去の状態を再現できることは、コンプライアンス要件を満たす上で不可欠です。
障害復旧とロールバック: リビジョン管理は、システム障害や人為的ミスからの復旧を容易にします。特定の時点の状態に戻すことができるため、データの損失やシステムの不整合を最小限に抑えることができます。
分散システムでの一貫性: マイクロサービスアーキテクチャにおいて、リソースリビジョンは分散システム全体の一貫性を維持する上で重要な役割を果たします。例えば、複数のサービスにまたがるトランザクションを、各サービスのリソースリビジョンを用いて追跡し、必要に応じて補償トランザクションを実行することができます。
A/Bテストと段階的ロールアウト: リビジョン管理機能は、新機能の段階的なロールアウトやA/Bテストの実施を容易にします。特定のユーザーグループに対して特定のリビジョンを提供することで、変更の影響を慎重に評価できます。
パフォーマンス最適化: リビジョン管理の実装には、効率的なデータ構造とアルゴリズムの選択が重要です。例えば、差分ベースのストレージを使用して、リビジョン間の変更のみを保存することで、ストレージ使用量を最適化できます。
セキュリティとアクセス制御: リビジョン管理を導入する際は、各リビジョンへのアクセス制御を適切に設計する必要があります。特に、機密情報を含むリビジョンへのアクセスを制限し、監査ログを維持することが重要です。
APIの進化とバージョニング: リソースリビジョンの概念は、APIそのもののバージョニング戦略と関連付けて考えることができます。APIの各バージョンを、特定の時点でのリソース定義のリビジョンとして扱うことで、APIの進化をより体系的に管理できる可能性があります。

リソースリビジョンとシステムアーキテクチャ

リソースリビジョンの設計は、システム全体のアーキテクチャに大きな影響を与えます。以下の点について考慮する必要があります。

データモデルとスキーマ設計: リビジョン管理をサポートするために、データベーススキーマの設計を適切に行う必要があります。例えば、メインのリソーステーブルとは別にリビジョンテーブルを作成し、効率的にクエリできるようにインデックスを設計することが重要です。
キャッシュ戦略: リビジョン管理は、キャッシュ戦略に影響を与えます。特定のリビジョンをキャッシュする場合、キャッシュの有効期限や更新戦略を慎重に設計する必要があります。
イベントソーシングとCQRS: リソースリビジョンの概念は、イベントソーシングやCQRS（Command Query Responsibility Segregation）パターンと親和性が高いです。これらのパターンを組み合わせることで、より柔軟で拡張性の高いシステムを構築できる可能性があります。
バックアップと災害復旧: リビジョン管理機能は、バックアップと災害復旧戦略に組み込むことができます。特定の時点のシステム全体の状態を、各リソースの適切なリビジョンを用いて再構築することが可能になります。
マイクロサービス間の整合性: 複数のマイクロサービスにまたがるリソースの場合、リビジョン管理を通じてサービス間の整合性を維持することができます。例えば、分散トランザクションの代わりに、各サービスのリソースリビジョンを用いた補償トランザクションを実装することが考えられます。

結論

第28章「Resource revisions」は、APIにおけるリソースリビジョン管理の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIの柔軟性、データの整合性、そして全体的なシステムの運用性を大きく向上させる可能性があります。

リビジョン管理を導入する際の考慮点を挙げます。

リソースリビジョンは、変更履歴の追跡、過去の状態の参照、誤った変更のロールバックを可能にする強力な機能です。
リビジョン管理の実装には、リビジョン識別子の設計、リビジョン作成戦略の選択、リビジョンの取得と一覧表示、復元機能の実装など、多くの考慮事項があります。
リソースリビジョンの導入には、ストレージ使用量の増加、パフォーマンスへの影響、複雑性の増加などのトレードオフがあります。これらを適切に管理することが重要です。
リビジョン管理は、監査とコンプライアンス、障害復旧とロールバック、分散システムでの一貫性維持など、多くの実践的な応用が可能です。
リソースリビジョンの設計は、データモデル、キャッシュ戦略、イベントソーシング、バックアップと災害復旧など、システム全体のアーキテクチャに大きな影響を与えます。

変更履歴の追跡が重要な環境や、複雑な分散システムでは、リソースリビジョンの実装が特に有効です。

ただしリソースリビジョンの導入には慎重な検討も必要です。特に、ストレージ使用量の増加、パフォーマンスへの影響、システムの複雑性の増加などの観点から、システムの要件と制約を十分に理解し、適切な設計決定を行う必要があります。

最後に、リソースリビジョンの設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単に個々のリソースの変更履歴を管理するだけでなく、システム全体の一貫性、信頼性、そして運用効率の向上にも大きく貢献します。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

リソースリビジョンの適切な実装は、システムの回復力を高め、データの整合性を保護し、変更管理を容易にする可能性があります。特に、マイクロサービスアーキテクチャやクラウドネイティブな環境では、この機能の重要性がより顕著になります。API設計者とシステム設計者は、これらの原則を深く理解し、実践することで、より堅牢で柔軟性の高いシステムを構築することができるでしょう。

リソースリビジョン管理は、単なる技術的機能を超えて、システム全体の品質と信頼性を向上させる重要な要素となります。適切に実装されたリビジョン管理システムは、変更の追跡、問題の診断、そして迅速な復旧を可能にし、結果としてシステムの運用性と信頼性を大きく向上させます。さらに、この機能は、コンプライアンス要件の遵守、データガバナンスの強化、そして長期的なシステム進化の管理にも貢献します。

API設計者とシステムアーキテクトは、リソースリビジョン管理の重要性を認識し、適切に実装することで、より堅牢で効率的、そして将来の変化に適応可能なシステムを構築することができます。これは、急速に変化し、常に新しい課題が生まれる現代のソフトウェア開発環境において、特に重要な価値となります。

29 Request retrial

"API Design Patterns" の第29章「Request retrial」は、API リクエストの再試行に関する重要な概念と実装方法について詳細に論じています。この章では、失敗したAPIリクエストのうち、どれを安全に再試行できるか、リトライのタイミングに関する高度な指数関数的バックオフ戦略、「雪崩現象」を回避する方法、そしてAPIがクライアントにリトライのタイミングを指示する方法について説明しています。

リクエスト再試行の必要性と概要

著者は、Web APIにおいてリクエストの失敗は避けられない現実であることを指摘することから議論を始めています。失敗の原因には、クライアント側のエラーや、APIサーバー側の一時的な問題など、様々なものがあります。特に後者の場合、同じリクエストを後で再試行することで問題が解決する可能性があります。

この概念は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。分散システムでは、ネットワークの不安定性やサービスの一時的な障害が頻繁に発生する可能性があるため、適切な再試行メカニズムは、システム全体の信頼性と回復力を大幅に向上させる可能性があります。

著者は、再試行可能なリクエストを識別し、適切なタイミングで再試行を行うための2つの主要なアプローチを提案しています。

クライアント側の再試行タイミング（指数関数的バックオフ）
サーバー指定の再試行タイミング

これらのアプローチは、システムの効率性を最大化しつつ、不要な再試行を最小限に抑えるという目標を達成するために設計されています。

クライアント側の再試行タイミング

著者は、クライアント側の再試行戦略として、指数関数的バックオフアルゴリズムを推奨しています。このアルゴリズムは、再試行の間隔を徐々に増やしていくことで、システムに過度の負荷をかけることなく、再試行の成功確率を高めます。

指数関数的バックオフの基本的な実装は以下のようになります。

use std::time::Duration;
use tokio::time::sleep;

pub async fn retry_with_exponential_backoff<F, Fut, E>(
    mut operation: F,
    max_retries: u32,
) -> Result<(), E>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<(), E>>,
{
    let mut last_error = None;

    for attempt in 0..max_retries {
        match operation().await {
            Ok(()) => return Ok(()),
            Err(e) => last_error = Some(e),
        }

        let delay = Duration::from_secs(2u64.pow(attempt));
        sleep(delay).await;
    }

    Err(last_error.expect("at least one attempt was made"))
}

しかし、著者はこの基本的な実装にいくつかの重要な改良を加えることを提案しています。

最大遅延時間の設定: 再試行の間隔が無限に長くなることを防ぐため。
最大再試行回数の設定: 無限ループを防ぐため。
ジッター（ランダムな遅延）の追加: 「雪崩現象」を防ぐため。

これらの改良を加えた、より洗練された実装は以下のようになります。

use rand::Rng;
use std::time::Duration;
use tokio::time::sleep;

pub async fn retry_with_exponential_backoff<F, Fut, E>(
    mut operation: F,
    max_retries: u32,
    max_delay: Duration,
) -> Result<(), E>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<(), E>>,
{
    let mut last_error = None;
    let mut rng = rand::thread_rng();

    for attempt in 0..max_retries {
        match operation().await {
            Ok(()) => return Ok(()),
            Err(e) => last_error = Some(e),
        }

        let delay = Duration::from_secs(2u64.pow(attempt)).min(max_delay);
        let jitter = Duration::from_millis(rng.gen_range(0..1000));
        sleep(delay + jitter).await;
    }

    Err(last_error.expect("at least one attempt was made"))
}

この実装は、システムの回復力を高めつつ、不必要な負荷を避けるバランスの取れたアプローチを提供します。

サーバー指定の再試行タイミング

著者は、APIサーバーが再試行のタイミングを明示的に指定できる場合があることを指摘しています。これは主に、サーバーが特定の情報（例：レート制限のリセットタイミング）を持っている場合に有用です。

この目的のために、著者はHTTPの"Retry-After"ヘッダーの使用を推奨しています。このヘッダーを使用することで、サーバーは正確な再試行タイミングをクライアントに伝えることができます。

use axum::{
    http::{Request, StatusCode},
    response::{IntoResponse, Response},
};

async fn handle_rate_limited_request<B>(req: Request<B>) -> Response {
    if is_rate_limited(&req) {
        let retry_after = calculate_retry_after();
        return (
            StatusCode::TOO_MANY_REQUESTS,
            [("Retry-After", retry_after.as_secs().to_string())],
        )
            .into_response();
    }
    // 通常の処理を続行
    StatusCode::OK.into_response()
}

クライアント側では、このヘッダーを検出し、指定された時間だけ待機してからリクエストを再試行します。

use reqwest::{Client, Request, Response};
use std::time::Duration;
use thiserror::Error;
use tokio::time::sleep;

#[derive(Debug, Error)]
pub enum RetryError {
    #[error("request error: {0}")]
    RequestError(#[from] reqwest::Error),
}

pub async fn send_request_with_retry(
    client: &Client,
    request: Request,
) -> Result<Response, RetryError> {
    let resp = client.execute(request.try_clone().unwrap()).await?;

    if resp.status() == reqwest::StatusCode::TOO_MANY_REQUESTS {
        if let Some(retry_after) = resp.headers().get("Retry-After") {
            if let Ok(retry_str) = retry_after.to_str() {
                if let Ok(seconds) = retry_str.parse::<u64>() {
                    sleep(Duration::from_secs(seconds)).await;
                    return Box::pin(send_request_with_retry(client, request)).await;
                }
            }
        }
    }

    Ok(resp)
}

この手法は、サーバーの状態や制約に基づいて、より正確で効率的な再試行戦略を実現します。

再試行可能なリクエストの判断

著者は、全てのエラーが再試行可能なわけではないという重要な点を強調しています。再試行可能なエラーとそうでないエラーを区別することは、効果的な再試行戦略の鍵となります。

一般的に、以下のようなガイドラインが提示されています。

再試行可能: 408 (Request Timeout), 429 (Too Many Requests), 503 (Service Unavailable) など。これらは一時的な問題を示唆しています。
再試行不可能: 400 (Bad Request), 403 (Forbidden), 404 (Not Found) など。これらは永続的な問題を示唆しています。
条件付き再試行可能: 500 (Internal Server Error), 502 (Bad Gateway), 504 (Gateway Timeout) など。これらは状況に応じて再試行可能かどうかが変わります。

この区別は、システムの効率性と信頼性を維持する上で重要です。不適切な再試行は、システムリソースの無駄遣いや、意図しない副作用を引き起こす可能性があります。

実践的な応用と考察

この章の内容は、実際のAPI設計と運用において重要です。特に以下の点が重要になります。

システムの回復力: 適切な再試行メカニズムは、一時的な障害から自動的に回復するシステムの能力を大幅に向上させます。これは特に、マイクロサービスアーキテクチャのような分散システムにおいて重要です。
効率的なリソース利用: 指数関数的バックオフやサーバー指定の再試行タイミングを使用することで、システムリソースを効率的に利用しつつ、再試行の成功確率を最大化できます。
ユーザーエクスペリエンス: エンドユーザーの視点からは、適切な再試行メカニズムは、一時的な問題を自動的に解決し、シームレスなエクスペリエンスを提供します。
運用の簡素化: 適切に設計された再試行メカニズムは、手動介入の必要性を減らし、運用タスクを簡素化します。
モニタリングと可観測性: 再試行の頻度や成功率を監視することで、システムの健全性や潜在的な問題を把握するための貴重な洞察が得られます。

結論

第29章「Request retrial」は、APIにおけるリクエスト再試行の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、システムの信頼性、効率性、そして全体的な運用性を大きく向上させる可能性があります。

再試行メカニズムを実装する際の原則です。

全てのエラーが再試行可能なわけではありません。エラーの性質を慎重に評価し、適切に再試行可能なものを識別することが重要です。
指数関数的バックオフは、効果的な再試行戦略の基礎となります。ただし、最大遅延時間、最大再試行回数、ジッターなどの改良を加えることで、より堅牢な実装が可能になります。
サーバー指定の再試行タイミング（Retry-Afterヘッダー）は、特定のシナリオにおいて非常に有効です。これにより、より正確で効率的な再試行が可能になります。
再試行メカニズムは、システムの回復力、効率性、ユーザーエクスペリエンス、運用性を向上させる重要なツールです。
再試行の実装には、システム全体のアーキテクチャと運用プラクティスとの整合性が必要です。

分散システムやクラウドネイティブ環境では、適切な再試行メカニズムの実装が不可欠です。

リクエスト再試行の設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単にエラーハンドリングを改善するだけでなく、システム全体の信頼性、スケーラビリティ、そして運用効率の向上にも大きく貢献します。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

リクエスト再試行の適切な実装は、システムの回復力を高め、一時的な障害の影響を最小限に抑え、全体的なユーザーエクスペリエンスを向上させる可能性があります。API設計者とシステム設計者は、これらの原則を深く理解し、実践することで、より堅牢で信頼性の高いシステムを構築することができるでしょう。

30 Request authentication

「API Design Patterns」の第30章「Request authentication」は、APIにおけるリクエスト認証の重要性、その実装方法、そしてトレードオフについて詳細に論じています。この章を通じて、著者はリクエスト認証が単なるセキュリティ機能の追加ではなく、APIの信頼性、完全性、そして全体的なシステムアーキテクチャにどのように影響を与えるかを明確に示しています。

リクエスト認証の必要性と概要

著者は、APIリクエストの認証に関する基本的な疑問から議論を始めています。「与えられたインバウンドAPIリクエストが、実際に認証されたユーザーからのものかどうかをどのように判断するのか」という問いに答えるために、著者は3つの重要な要件を提示しています。

オリジン（Origin）: リクエストが主張する送信元から本当に来たものかどうかを確認する能力。
完全性（Integrity）: リクエストの内容が送信後に改ざんされていないことを確認する能力。
否認防止（Non-repudiation）: 送信者が後からリクエストの送信を否定できないようにする能力。

これらの要件は、現代のマイクロサービスアーキテクチャやクラウドネイティブ環境において特に重要です。分散システムでは、サービス間の通信の信頼性と完全性を確保することが不可欠であり、これらの要件を満たすことで、システム全体のセキュリティと信頼性が大幅に向上します。

著者は、これらの要件を満たすソリューションとして、デジタル署名の使用を提案しています。デジタル署名は、公開鍵暗号方式を利用した非対称な認証メカニズムで、以下の特性を持ちます。

署名の生成に使用する秘密鍵と、検証に使用する公開鍵が異なる。
署名はメッセージの内容に依存するため、メッセージの完全性を保証できる。
秘密鍵の所有者のみが有効な署名を生成できるため、否認防止が可能。

Request authenticationはそこそこに入り組んだ分野でもあるのでセキュア・バイ・デザインなどもオススメです。

syu-m-5151.hatenablog.com

デジタル署名の実装

著者は、デジタル署名を用いたリクエスト認証の実装に関して詳細なガイダンスを提供しています。主なステップは以下の通りです。

クレデンシャルの生成: ユーザーは公開鍵と秘密鍵のペアを生成します。
登録とクレデンシャル交換: ユーザーは公開鍵をAPIサービスに登録し、一意の識別子を受け取ります。
リクエストの署名: ユーザーは秘密鍵を使用してリクエストに署名します。
署名の検証: APIサーバーは公開鍵を使用して署名を検証し、リクエストを認証します。

これらのステップを実装するためのRustのコード例を以下に示します。

use rsa::{
    pkcs1v15::{SigningKey, VerifyingKey},
    signature::{Signer, Verifier},
    RsaPrivateKey, RsaPublicKey,
};
use sha2::Sha256;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum CryptoError {
    #[error("key generation failed: {0}")]
    KeyGeneration(#[from] rsa::Error),
    #[error("signature error: {0}")]
    Signature(#[from] rsa::signature::Error),
}

// クレデンシャルの生成
pub fn generate_credentials() -> Result<RsaPrivateKey, CryptoError> {
    let mut rng = rand::thread_rng();
    Ok(RsaPrivateKey::new(&mut rng, 2048)?)
}

// リクエストの署名
pub fn sign_request(
    private_key: &RsaPrivateKey,
    request: &[u8],
) -> Result<Vec<u8>, CryptoError> {
    let signing_key = SigningKey::<Sha256>::new(private_key.clone());
    let signature = signing_key.sign(request);
    Ok(signature.to_vec())
}

// 署名の検証
pub fn verify_signature(
    public_key: &RsaPublicKey,
    request: &[u8],
    signature: &[u8],
) -> Result<(), CryptoError> {
    let verifying_key = VerifyingKey::<Sha256>::new(public_key.clone());
    let sig = rsa::pkcs1v15::Signature::try_from(signature)
        .map_err(|_| CryptoError::Signature(rsa::signature::Error::new()))?;
    verifying_key.verify(request, &sig)?;
    Ok(())
}

この実装例では、RSA暗号化を使用してクレデンシャルの生成、リクエストの署名、署名の検証を行っています。実際の運用環境では、これらの基本的な関数をより堅牢なエラーハンドリングとロギングメカニズムで包む必要があります。

リクエストのフィンガープリンティング

著者は、リクエスト全体を署名するのではなく、リクエストの「フィンガープリント」を生成して署名することを提案しています。このフィンガープリントには以下の要素が含まれます。

HTTPメソッド
リクエストのパス
ホスト
リクエストボディのダイジェスト
日付

これらの要素を組み合わせることで、リクエストの本質的な部分を捉えつつ、署名対象のデータサイズを抑えることができます。以下に、フィンガープリントの生成例を示します。

use axum::http::Request;
use base64::{engine::general_purpose::STANDARD, Engine};
use chrono::Utc;
use sha2::{Digest, Sha256};

pub fn generate_fingerprint<B>(req: &Request<B>, body: &[u8]) -> String {
    let body_digest = Sha256::digest(body);
    let digest_b64 = STANDARD.encode(body_digest);

    let elements = [
        format!(
            "(request-target): {} {}",
            req.method().as_str().to_lowercase(),
            req.uri().path()
        ),
        format!("host: {}", req.uri().host().unwrap_or_default()),
        format!("date: {}", Utc::now().format("%a, %d %b %Y %H:%M:%S GMT")),
        format!("digest: SHA-256={}", digest_b64),
    ];

    elements.join("\n")
}

このアプローチにより、リクエストの重要な部分を効率的に署名できるようになります。

実践的な応用と考察

この章の内容は、実際のAPI設計と運用において重要です。特に以下の点が重要になります。

セキュリティと信頼性: デジタル署名を使用したリクエスト認証は、APIの安全性と信頼性を大幅に向上させます。これは特に、金融取引や医療情報など、機密性の高いデータを扱うシステムで重要です。
マイクロサービスアーキテクチャでの応用: サービス間通信の認証に適用することで、マイクロサービスアーキテクチャ全体のセキュリティを強化できます。
スケーラビリティの考慮: デジタル署名の検証は計算コストが高いため、大規模なシステムでは適切なキャッシング戦略やロードバランシングが必要になる可能性があります。
運用上の課題: 秘密鍵の安全な管理や、公開鍵の配布・更新メカニズムの構築が必要になります。これらは、適切なシークレット管理システムやPKIインフラストラクチャの導入を検討する良い機会となります。
監視とロギング: 署名の検証失敗や不正なリクエストの試行を適切に監視・ロギングすることで、システムの安全性をさらに向上させることができます。

結論

第30章「Request authentication」は、APIにおけるリクエスト認証の重要性と、その適切な実装方法を明確に示しています。著者の提案する設計原則は、APIのセキュリティ、信頼性、そして全体的なシステムアーキテクチャを大きく向上させる可能性があります。

リクエスト認証を実装する上での5つの原則です。

リクエスト認証は、オリジン、完全性、否認防止の3つの要件を満たす必要があります。
デジタル署名は、これらの要件を満たす強力なメカニズムを提供します。
リクエストのフィンガープリンティングは、効率的かつ効果的な署名方法です。
この認証方式の実装には、適切なクレデンシャル管理と運用プラクティスが不可欠です。
パフォーマンスとスケーラビリティのトレードオフを慎重に検討する必要があります。

高度なセキュリティ要件を持つシステムや、複雑な分散アーキテクチャを採用している環境では、この認証方式の実装が特に重要です。

ただしこの認証方式の導入には慎重な検討も必要です。特に、パフォーマンス、運用の複雑さ、開発者の学習曲線の観点から、システムの要件と制約を十分に理解し、適切な設計決定を行う必要があります。

最後に、リクエスト認証の設計はシステム全体のアーキテクチャと密接に関連しています。適切な設計は、単にAPIのセキュリティを向上させるだけでなく、システム全体の信頼性、運用効率、そして将来の拡張性にも大きく貢献します。したがって、API設計者は、個々のエンドポイントの設計だけでなく、システム全体のアーキテクチャとの整合性を常に意識しながら設計を進める必要があります。

この章の内容は、特に大規模で長期的に運用されるシステムの設計において重要です。デジタル署名を用いたリクエスト認証の適切な実装は、システムのセキュリティを大幅に向上させ、潜在的な脅威や攻撃から保護する強力な手段となります。API設計者とシステム設計者は、これらの原則を深く理解し、実践することで、より堅牢で信頼性の高いシステムを構築することができるでしょう。

おわりに

この文章を書き終えようとしている。日曜の夜だ。冒頭で書いた「日曜の昼過ぎ」から、何時間か経った。コーヒーはとっくに冷めている。

書いている間も、ずっと考えていた。この本を読んだことで、自分は変わったのだろうか。正直に言うと、分からない。来週また似たような障害を起こすかもしれない。「とりあえず動けばいい」と思ってしまうかもしれない。たぶん、思う。

Design Patternsは設計そのものではない。パターンを知っているだけで、良い設計ができるわけではない。それは分かっている。分かっているが、何も知らないよりはマシだと思いたい。思いたいだけかもしれない。

480ページを読み切って、残ったものがある。「この原則はなぜ生まれたのか」と問う習慣だ。リソース指向の章を読みながら、「これはRPCへの反動で生まれたのかもしれない」と想像した。その想像が正しいかは分からない。でも、次に新しいパラダイムが来たとき、「これは何への反動か」と問えるようになった気がする。気がするだけかもしれないが。

原則を暗記しても、たぶん使えない。原則が生まれた文脈を追体験する方が、長く使える。そう思うことにしている。

この記事を読んで、何かが変わる人がいるのかは分からない。私自身、書いたことで変わったのかも分からない。ただ、書いた。書いたという事実だけが残る。

窓の外は暗くなっていた。明日は月曜だ。また同じような仕事が始まる。また「とりあえずこれで走らせよう」と言いたくなる瞬間が来るだろう。そのとき、あのリリース前夜のことを思い出せるかどうか。思い出したところで、違う判断ができるかどうか。正直、分からない。でも、「なぜこう作るのか」と問えるようになった。問えるようになった気がする。それだけでも、あの日の自分より、少しだけマシなのかもしれない。

あなたがさっきまで読んでいた技術的に役立つ記事は、10年後も使えるでしょうか。ほとんどの場合でいいえ。でも、それでいいのだと思う。

最初に戻る。

はじめに

目次

Part 1 Introduction

1 Introduction to APIs

Web APIの特性と重要性

API設計アプローチの比較

「良い」APIの特性

運用可能性とSREの視点

表現力と使いやすさ

シンプル性と柔軟性のバランス

予測可能性とコード一貫性

著者の主張に対する補完的視点

総括と実践への応用

継続的改善と進化の重要性

結論

2 Introduction to API design patterns

API設計パターンの定義と重要性

API設計パターンの構造

実践的な適用：Twapiの事例研究

メッセージのリスト化

データのエクスポート

API設計パターンの適用：早期採用の重要性

結論

Part 2 Design principles

3 Naming

命名の重要性

良い名前の特性

言語、文法、構文の選択

コンテキストと命名

データ型と単位

結論

4 Resource scope and hierarchy

リソースレイアウトの重要性

リソース間の関係性

エンティティ関係図の活用

適切な関係性の選択

アンチパターンの回避

実践的な応用と考察

結論

5 Data types and defaults

データ型の重要性と課題

プリミティブデータ型の扱い

コレクションと構造体

実践的な応用と考察

結論

Part 3 Fundamentals

6 Resource identification

識別子の重要性と特性

実装の詳細

識別子の階層と一意性のスコープ

UUIDとの比較

実践的な応用と考察

結論

7 Standard methods

標準メソッドの重要性と概要

実装の詳細とベストプラクティス

標準メソッドの適用と課題

実践的な応用と考察

結論

8 Partial updates and retrievals

部分的な更新と取得の動機

フィールドマスクの実装

部分的な更新と取得の課題

実践的な応用と考察

フィールドマスクの高度な使用法

部分的な更新と取得の影響

結論

9 Custom methods

カスタムメソッドの必要性と動機

カスタムメソッドの実装

副作用の取り扱い

リソースvs.コレクション

ステートレスカスタムメソッド

実践的な応用と考察

結論

10 Long-running operations

長時間実行操作の必要性と概要

LROの実装

LROの状態管理と結果の取得

LROの制御と管理