APIデザイン・パターン

A1.「月に1回」のような周期は暦に依存し、月や年は長さが一定ではないため、単なる「秒数」では本来の意味を保てません。時間単位を区別できる専用の表現の方が利用者の意図を正しく表せ、表現力で優れます。「単位など名前に書ききれない情報は専用のデータ型で表す」という指針に沿い、後者がより良い選択です。

A2. 混乱を招きます。同じ「G」でも10^9（ギガ＝SI接頭辞）と2^30（ギビ＝2進接頭辞）は別物で、しかも一方はバイト、もう一方はビットです。sizeGBとbandwidthLimitGibという名前の差だけで単位・基数の違いを背負わせると取り違えやすく、単位は名前に頼らず専用のデータ型で明示し、命名は一貫させるべきです。

A1. 多くの場合、BookmarkとFolderは別々のリソースにモデル化するのが素直です。両者は扱うデータと操作がともに異なり、それぞれ独立にget/update/deleteしたい（単独でアトミックに扱う）からです。単一リソース＋型インライン（ポリモーフィズム、第16章）は「両者を1つの並びとしてまとめて扱うこと自体に意味がある」場合に限って選ぶべきで、単なる整理用途では過剰です。

A2. 例として、ユーザーとグループは多対多（User ⟷ Group、間にMembershipを挟む）、ユーザーと投稿は1対多（User 1 ─ ∞ Post）、ユーザーとプロフィールは1対1（User 1 ─ 1 Profile）です。ER図ではカラスの足記法で「多」を鳥の足、「1」を縦棒で示し、各端の基数を明示します。多対多は直接つながず関連リソースを挟むのが定石です。

A1. UTF-16は日本語だけを見れば効率的でも、相互運用性で不利です。Web標準・多くのツール・JSONはUTF-8が事実上の標準で、UTF-16にすると他システムとの連携やバイト順（BOM/エンディアン）の扱いで問題が生じます。識別子や文字列は原則UTF-8でエンコードすべきで、目先の効率より長期の互換性を優先します。

A2. ブール値は肯定形で名付ける原則から、disableArchivingではなくarchiveOldMessages（trueで有効）のように肯定形にします。ただしオン/オフだけのブールより、保持期間を数値（例messageRetention）で持たせる方が表現力に優れ、将来「48時間」などの要求にも応えられます。単なる無効化フラグは最良とは限りません。

A3. 書いている言語が任意精度でも、利用者側（JavaScriptなど）はIEEE754倍精度しか持たず、2^53を超える整数を失います。したがって安全のため、大きくなりうる数値は文字列としてシリアライズすべきです。サーバー言語が扱えることと、すべてのクライアントが扱えることは別問題なので、標準のJSON数値表現に頼り切るのは危険です。

A4. 列挙型は避けるべきです。サポート言語は将来増減し、列挙値の追加・削除は既存クライアントの互換性を壊しやすいからです。代わりにBCP 47言語タグ（“ja”、“en-US” など）の文字列フィールドにし、検証はサーバー側で行うのが最適です。集合が開いている/進化するものは文字列＋サーバー検証が定石です。

A5. マップにはキー数の上限に加え、キー長と値長それぞれの上限を設けます（例キー100文字・値500文字）。値の大きさが不均一なら、合計バイト数に上限を設けて「小さな値を多数」か「大きな値を少数」かを利用者へ委ねる方法もあります。いずれにせよ無制限とせず、レスポンス肥大化やDoSを防ぐ有界な設計とします。

A1. 識別子の長さ（ビット数）に比例してチェック桁を増やす設計にします。たとえばnバイトごとに1チェック文字を割り当て、全体に対する剰余（Crockford互換の基数のmod）でチェック値を計算します。識別子が長いほど誤り検出能力が上がり、長い識別子での打ち間違い見逃しを減らせます。デコード時はチェック文字を再計算して一致を確認します。

A2. 空間は2^16 = 65,536個です。誕生日問題より、衝突確率が約50%になるのは概ね √(2^16) ＝ 256個前後を生成したとき（厳密には約300個で50%）です。つまり数百個発行しただけで衝突が現実的になり、16ビットは識別子として小さすぎることが分かります。実用では十分大きな空間（128ビット級）を使うべきです。

A3. 16ビットを領域分割し、ノードごとに別々の範囲（プレフィックス）を割り当てる方法が使えます。たとえば上位ビットをノードID、下位ビットを各ノードのローカルカウンタにすれば、中央のカウンタを共有せずにノード間衝突を避けられます。あるいは各ノードが「自分の担当ブロック」を事前に予約して払い出す方式でも、単一カウンタなしに一意性を保てます。

A1. 原理上はreplace（全体置換）で作成と更新のどちらも表現できますが、推奨されません。replaceは「リソースが無ければ作り、ある場合は丸ごと置き換える」になり、部分更新や、作成と更新で異なる検証・権限を分けられません。利用者の意図（新規と変更のどちらか）が曖昧になり予測可能性が下がるため、createとupdateを分けて提供するのが定石です。

A2. 書き込み後すぐ読めない（結果整合性）なら、createのレスポンスでサーバーが返した値を信頼できる正とし、直後のgetでは「まだ見えない」可能性を受け入れます。選択肢としては、read-your-writes一貫性を提供する・作成完了をLRO（第10章）で表す・作成直後はレスポンスのボディを唯一の真実として扱う、などがあります。

A3. PUTは本来「リソース全体の置換」を意味し、送らなかったフィールドは消える解釈になります。標準のupdateは部分更新（フィールドマスク、第8章）を扱うため、部分変更を表すPATCHが適切です。PUT相当の全体置換はreplaceに対応します。

A4. 呼ぶたびにカウンターが増えるgetはべき等ではありません（毎回状態が変わる）。そもそもgetは副作用を持つべきではなく、これは設計上の不吉な兆候です。deleteもべき等ではありません。1回目は削除に成功しますが、2回目は「存在しない」状態になり、結果（や返るエラー）が変わりうるからです。

A5. 総数は巨大コレクションで毎回数えると高コストで、ページングと相性も悪く、同時更新で不正確になります。任意ソートはインデックスの無いフィールドで重くなり、ページトークンの一貫性も保ちにくくします。どちらも性能・スケール・一貫性を損なうため、標準のlistでは基本的に避け、本当に必要なら限定的・明示的に提供します。

A1. 管理者を単純な配列で持つと、部分更新できず（1人追加するのに配列全体を送る必要があり衝突しやすい）、要素の順序や重複の扱いも曖昧になります。代替として、管理者を関連付け（アソシエーションリソースやadd/removeカスタムメソッド／第14・15章）でモデル化すれば、個別に追加・削除でき、関係のメタデータ（役割など）も持てます。

A2. フィールドマスクで対象キーを指定し、その値をnull（または欠落）として更新します。マスクにsettings.themeのように当該キーを含め、値を送らない／nullにすることで、そのキーだけを安全に削除でき、他のキーには触れません。

A3. 取得リクエストにフィールドマスク（例field_mask=name,emailやネストのprofile.bio）を付け、サーバーは指定フィールドだけを返します。これにより巨大リソースの一部だけを効率よく取得できます。

A4. 取得では「マスク省略＝全フィールド」を既定にします。明示したいなら _（ワイルドカード）を全フィールドの意味として使う方法もあります。更新では「送られたフィールドの存在から暗黙にマスクを推測する」既定にし、全体更新を意図するなら _ を使います。

A5. キー名自体にドットを含むため、そのままではsettings.hello.world（ネスト指定）と区別できません。キーを引用してエスケープし、settings.“hello.world” のように表記して「hello.worldというキー1つ」を指すようにします。マスクの構文でキーをクォートできるよう設計しておく必要があります。

A1. 標準のcreateは副作用を持つべきではないので、メール送信などの副作用が本質的に必要なら、それをカスタムメソッドとして切り出すのが適切です。ただし副作用は控えめにし、必ずドキュメント化します。単に作成のついでに軽い副作用が起きる程度なら新メソッドは不要で、利用者が驚く副作用ほどカスタムメソッドで明示すべきです。

A2. 複数のリソースをまたいで作用する操作（一括処理など）は、特定の親ではなくコレクションを対象にします（例 /messages:export）。単一リソースに作用するならそのリソースを、親そのものの状態を変えるなら親を対象にします。「対象は作用範囲に一致させる」のが原則です。

A3. 純粋な計算（例その場翻訳）をステートレスなカスタムメソッドで出すと手軽ですが、後から「結果を保存して参照したい」「履歴を残したい」というステートフルな要求が出たとき、リソース指向への作り直しが難しくなります。最初からリソースとして表せないか検討し、ステートレス特化は慎重に選ぶべきです。

A1. Operationは「対象リソースが作成される前」や「削除する操作」にも対応する必要があり、対象の子に置くと、対象がまだ無い/消えた場合に置き場所が無くなります。トップレベル（/operations/abc）に置けば、どの操作にも一様にアクセスでき、対象のライフサイクルから独立して進捗・結果を追えます。

A2. 完了した操作の記録を永久に保持すると、際限なく溜まりストレージとクエリを圧迫します。一定期間（例30日）で破棄する有効期限を設ければ、利用者が結果を取りに来る十分な猶予を与えつつ、古い操作を自動的に片付けられます。

A3. cancelは処理の中止を要求し、操作は「完了（done=true）」かつ「エラー（例CANCELLED）」として決着します。すでに途中まで進んだ副作用が残ることはあり得るため、キャンセルは取り消しではない点に注意が必要で、必要なら部分結果やロールバックの扱いを明示します。

A4. 進捗の目安として完了率（progressPercent）は利用者体験に有用ですが、正確な割合を出せない処理も多く、過信されると問題です。出せるなら「あくまで推定」として提供し、出せないならステージ名や処理済み件数など別のメタデータで表す方が誠実です。

A1. 設定（ジョブの作成・更新）と実行（run）を別々のメソッドに分けることで、それぞれに異なるアクセス制御を割り当てられます。管理者だけがジョブを定義し、運用者やスケジューラはrunだけを呼べる、という分離が自然に表現でき、これがジョブパターンの利点の1つです。

A2. runの直接の結果はExecutionリソース（その実行の記録）であるべきです。実行が生成した本来のリソースはExecutionから参照（またはLROの結果）として辿れるようにします。こうすれば「いつ・どの実行が・何を作ったか」の履歴が一貫して残ります。

A3. Executionは「ジョブが実行された事実の記録」であり、実行の副産物として生まれるものです。利用者がcreateで勝手にExecutionを作れると、実際には走っていない実行の偽の記録ができ、履歴の意味が壊れます。よってExecutionは読み取り専用（取得・一覧のみ）にします。

A1. 単純なサイズだけで決めるのではありません。データ量が大きく毎回親と返すと無駄・別個のセキュリティ要件・親と大きく異なる更新頻度・複雑な構造、といった理由があるときに分割します。これらが無ければプロパティのままで十分で、分割はコスト（別リクエスト）に見合う理由があるときだけ行います。

A2. シングルトンは親と共に必ず1つ存在し、親のライフサイクルに従うため、独立してcreate/deleteされるべきではありません（親があれば常に在り、親が消えれば共に消える）。よって作成・削除は無く、参照（get）と変更（update）だけを提供します。

A3. deleteは「存在しなくなる」ことを意味しますが、シングルトンは消えてはいけません。やりたいのは「既定状態に戻す」ことなので、意味の異なるdeleteを流用せず、初期化を表すresetカスタムメソッドを用意します。これで「消去」と「初期化」を取り違えずに済みます。

A4. シングルトンは「親リソースに固有の付随データ」を表す仕組みです。それをさらにシングルトンの下にネストすると階層が複雑化し、本来プロパティで足りるデータを過剰に分割することになります。シングルトンは実体リソースに直接付くべきで、入れ子にはしません。

A1. 参照先が消えても当時の値を残したい場合（履歴・監査・スナップショット的な意味）や、参照先の可用性を問わず高速に読みたい場合です。たとえば注文時の住所や価格は、後で元リソースが変わっても「その時点の値」を保持したいのでコピーが適切です。ただしコピーは時間とともに陳腐化する点を受け入れます。

A2. 分散したリソース間で常に整合性（参照先が必ず存在する保証）を強制すると、削除のたびに全参照を検査・連鎖更新する必要があり、スケールしません。多くのケースでは「参照先は消えうる、消えたら参照は無効」と割り切る方が現実的で、利用者にもそう期待させるべきです。

A3. 利用者はその保証に依存して設計するため、後から保証を外すと、依存していたコードが静かに壊れます。互換性の観点から、いったん与えた強い保証の撤回は破壊的変更になりがちです。だから最初から保証しすぎない（弱い保証にとどめる）のが安全です。

A1. 中間リソースMembershipを作り、/chatRooms/{room}/membershipsにuserId・chatRoomId・role・joinedAtを持たせます。Membership自体を標準メソッドでget/list/create/deleteでき、関係に付随するメタデータ（役割・参加時刻）も自然に表現できます。多対多はこの関連リソースでモデル化します。

A2.「現在の参加状態」と「履歴」を分けます。MembershipにjoinedAt・leftAtを持たせ、leftAtが空のものを「現在参加中」とみなし、その一意性制約（同一user×roomでleftAt=nullは1件まで）で二重参加を防ぎます。退出時は新規作成せずleftAtを埋め、再参加で新しいMembershipを作れば、過去の出入りが履歴として残ります。

A1. 関係そのものに付随するメタデータ（役割・参加日など）が不要で、単に結びつきの有無だけを管理したい場合です。中間リソースは柔軟ですが重く、メタデータが無ければadd/removeのカスタムメソッドの方が軽量で扱いやすくなります。

A2. 通常はRecipeが管理リソース（メタリソース）で、Ingredientが関連付けられる側です。POST /recipes/123:addIngredientのようにレシピに対して材料を足し引きします。「どちらに対して操作したいか（所有・集約の中心はどれか）」で管理側を選びます。

A3. 管理リソース上の標準listを使います（例GET /recipes/123/ingredients）。add/removeで関係を編集し、参照の取得は通常のlistに任せるのがこのパターンの形です。

A4. 集合への追加なので冪等に扱い、すでに存在する関係を再度addしても二重には入らず、状態は変わりません（エラーにせず成功として扱うのが無難）。重複が意味を持たない関係では「あれば何もしない」が自然な振る舞いです。

A1.「同じコレクション内に混在させ、まとめて一覧・並べ替えしたい」なら意味がありますが、フォルダとブックマークは振る舞いが異なり別々に扱う場面が多いので、無理に1リソースへ統合する必要は薄いです。まとめて取得することに本質的な意味があるかで判断し、無ければ別リソース（第4章）の方が明快です。

A2. 型の種類は将来増えうるため、列挙型だと値の追加で互換性を壊しやすいからです。文字列＋サーバー側検証にすれば、新しい型を後から安全に足せ、既存クライアントを壊しません。進化する集合は文字列で表すのが定石です。

A3. 厳格に弾くと、型の進化やクライアントの食い違いで些細な不一致でも壊れてしまい、互換性が下がります。必要なデータの有無だけを確認し、無関係なデータは寛容に無視する方が、前方・後方の互換性を保てます（ロバストネス原則）。

A4. リソースはポリモーフィックでよくても、メソッドの「振る舞いの契約」は型ごとに分岐すると後から変えにくく、利用者に予測不能な挙動を強います。UpdateResource()は型ごとに全く違う動きをすると、検証・権限・副作用がばらつき、保守も難しくなります。リソースはポリモーフィックに、メソッドは単型に保つべきです。

A1. 子リソースは原則一緒にコピーしますが、ケースバイケースで「どこまで深くコピーするか」を決めます。複製対象を参照する外部リソースについては、参照ごと複製するか、新しいコピーを指すよう貼り替えるかを明示的に設計します。曖昧にせず、コピーの境界を定義することが重要です。

A2. 外部システムをまたぐ強い参照整合性は一般に保証すべきではありません（コストが高く脆い）。必要なら、移動・コピー後に参照を更新するベストエフォートの仕組みを設け、保証ではなく「無効になりうる参照」として扱います。第13章と同様、整合性は強制しないのが現実的です。

A3. 操作をできる限りアトミックに行い、コピー時点のスナップショット（またはリビジョン、第28章）を基準にします。途中で他者の変更が混ざらないよう一貫した時点のデータを使い、必要なら版識別子やエタグで「どの時点を写したか」を明示して検証できるようにします。

A4. 移動先の新しい親のポリシーが適用されるべきです。リソースは新しい場所（住所）に属するので、移動後はその場所の規則に従います。これにより「移動して権限の制約を回避する」抜け道を防げます。移動の最中は、移動元・移動先双方の権限を確認するのが安全です。

A1. 結果を要求と同じ順序で返せば、利用者は位置（インデックス）で要求と結果を対応づけられます。順序が保証されないと、どの結果がどの要求のものか分からず、IDで突き合わせる余計な処理が必要になり、欠落や取り違えのもとになります。

A2. 不整合はエラーとして拒否すべきです（例400 Bad Request）。バッチはアトミックなので、1件でも親の不一致があればバッチ全体を失敗させ、部分的に適用しないようにします。親をまたぐ場合はワイルドカード - を使い、各リクエストにフルパスを書かせて整合を取ります。

A3. 一部だけ成功すると中途半端な状態になり、利用者はどこまで適用されたか分からず復旧が困難です。全部成功か全部失敗（アトミック）にすれば結果が明快です。どうしても部分成功を許すなら、それはバッチではなく各要素の個別結果（成功/失敗）を返す別物として定義し、その旨を明示する必要があります。

A4. HTTP DELETEはボディを持たせにくく、削除対象IDのリストのような複雑な入力を運べません。POSTなら本体に対象の一覧や条件を載せられます。バッチや条件削除は「コレクションに対するアクション」としてカスタムメソッド（POST + コロン記法）で表すのが自然です。

A1. 条件に一致するものを一括で消すのは極めて危険で、フィルタの誤りで意図せず大量のデータを失いかねません。標準のdeleteやバッチdeleteで足りるなら不要で、本当に「条件指定の一括削除」が必須なときだけ提供すべきです。

A2. 取り返しのつかない一括削除を、うっかり本実行してしまう事故を防ぐためです。既定を検証（validateOnly相当）にして「何件消えるか」を返すだけにし、本当に消すには明示的なフラグを必要とすることで、安全になります。

A3. 空フィルタを「全件一致」と解釈すると、全データ削除という最悪の事故になります。よって空フィルタは安全側に倒し、エラーにする（何も対象にしない、もしくは明示的な「全件」指定を別途要求する）べきです。既定でドライランなのも併せて被害を防ぎます。

A4. 一貫性のため、purgeも通常のdeleteと同じ意味（論理削除をサポートするなら論理削除）にするのが基本です。物理的に消すのはexpungeの役割なので、purgeでは論理削除に倒し、完全消去は別途expunge相当で行う設計が自然です。

A5. 影響件数は、本実行前に「これだけ消える」と利用者へ規模を知らせ、誤った広すぎるフィルタに気づかせるためです。マッチのサンプルを併せて返せば、「本当に意図した対象か」を具体的に確認でき、ドライランの安全性がさらに高まります。

A1. クライアント生成のリクエスト識別子（第26章の冪等キー）を各エントリーに付け、サーバーが既知のIDを重複として弾く方法が有効です。匿名書き込みは後から個別に消せないので、入口で冪等性を効かせて重複取り込みを防ぐのが定石です。

A2. writeは「アドレスを持たない匿名エントリー」を書く操作なので、IDやリソース表現を返すと「アドレス指定可能」という前提と矛盾します。LROを返すと、そのOperationの結果として書いたものを参照でき、結局アドレスを与えてしまうため不適切です。返すのはステータスコードだけにします。

A3.「受理したがまだ処理していない」はHTTP 202 Acceptedで表すのが一般的です。ほとんどの匿名書き込みでは、202（または単純な200）でステータスだけ返し、結果整合で後追い処理する形が最良です。個別追跡が要るならエントリーではなくリソース化を検討します。

A1.「最大」にしておけば、サーバーは全件揃う前でも用意できた分だけ早く返せ、タイムアウトや無駄な待ちを避けられます。正確な件数を常に満たそうとすると、内部の都合（シャード差・フィルタ）で性能が落ちます。利用者は「最大N件、足りなければ少なく返る」と理解すべきです。

A2. 空白は既定値を使い、負や0は不正としてエラーにする（または既定に丸める）べきです。巨大な値はサーバー側の上限（例100）にクランプします。いずれも無制限を許さず、安全な範囲に正規化することで、過大なレスポンスやDoSを防ぎます。

A3. レスポンスにnextPageTokenが無いことを「終わり」の合図とします。「結果が空＝終わり」と判断してはいけません（途中で空ページが返ることもあるため）。トークンの有無だけで継続/終了を判定します。

A4. 問題ありません。ページトークンは不透明で、各リソース種・各クエリの事情に応じて有効期限を決めてよいものです。利用者はトークンの中身や寿命に依存すべきでないので、種類ごとに有効期限が違っても構いません。

A5. 中身を公開すると利用者がそれに依存し、内部実装（オフセット方式や並び順）を変えられなくなるうえ、改ざんで不正なクエリを作られる恐れもあります。トークンは「黒い箱」とし、サーバー側でエンコード（必要なら署名・暗号化）して、利用者はそのまま返すだけにするのが望ましい実現です。

A1. 構造化（JSONのAND/ORツリーなど）は、表現したい条件が増えるたびにスキーマを拡張せねばならず硬直的で、進化させにくい点が欠点です。SQLライクな文字列なら、サーバー側のパーサを拡張するだけで新しい演算子・関数を足せ、表現力と進化性で勝ります。

A2. 配列はアトミックな集合として扱うべきで、要素の位置（添字）は同時編集や並べ替えで簡単にずれるからです。tags[0]= “x” のような位置指定は壊れやすく、メンバーシップ（“x” IN tags）で判定するのが正しい設計です。

A3. 厳格にエラーにせず、「存在しないキー＝値が無い（条件に一致しない）」として寛容に扱うべきです。エラーで弾くと、データのばらつきでフィルタが頻繁に失敗し使いにくくなります。無いものは静かに不一致とみなす方が頑健です。

A4. 提供する関数を使い、たとえばends_with（name, “man”）のように書きます。基本比較で足りない接尾辞一致のような要求には、ドキュメント化した関数（starts_with()・ends_with()・lower() など）を用意しておき、それをフィルタ文字列内で呼べるようにします。

A1.「どこに・どう出し入れするか（ストレージ：S3/GCS、URI、認証）」と「バイト列をリソース表現とどう変換するか（形式：CSV/JSON、列対応）」は本来独立した関心事だからです。直交させておけば、ストレージと形式を独立に選べるので、組み合わせの自由度と再利用性が高まります。1つに混ぜると組み合わせのたびに重複が生じます。

A2. ポイントインタイム読み取り（ある時点の一貫スナップショット）をサポートするのが最も確実です。それが無ければ、エクスポート中の書き込みを止める、リビジョンやタグで時点を固定する、などの手段があります。最良はスナップショット読み取りで、これが無い限り「最新とは限らない」前提を受け入れます。

A3. import/exportはバックアップ/リストアとは別物なので、識別子の保存は保証されず、インポートは通常「新しいID」で新規作成しがちです。同一IDの保持が必要なら、それはリストアの領域です。エクスポートに識別子を含めるかは設計判断ですが、インポートで同一IDを再現できる前提に立つべきではありません。

A4. 一概には消しません。エクスポート先は外部ストレージで、部分的に書かれたファイルの扱いは利用者やストレージの方針に依存するからです。中途半端な出力が誤って使われないよう、未完了を示す印（一時名・マーカー）を付け、完了時にコミットする方式が安全です。自動削除はデータ消失リスクとのトレードオフで決めます。

A5. 原則は1リソース型ずつですが、関連まで含めたいなら、それはバックアップ/リストアに近い機能として設計します。子・参照を含める場合、識別子の対応関係（旧ID→新IDのマッピング）を保持・再構築する仕組みが必要で、参照整合性をどう保つかを明示します。安易にimport/exportを拡張せず、専用のバックアップ機構に委ねるのが無難です。

A1. 一般に後方互換ではありません。既定値に依存していた利用者は、値を変えると挙動が静かに変わるからです。一見無害でも「省略時にこうなる」前提に依存するコードを壊しうるので、破壊的変更として扱うのが安全です。

A2. 複数バージョンを併走させ、安定版を長期サポートしつつ新版で新機能を出すのが定石です。明文化した互換性ポリシーで「何を・どれだけの期間保証するか」を示し、安定を望む顧客は旧版に留まり、先進性を望む利用者は新版へ移れるようにします。日付ベースのバージョニングも段階移行に有効です。

A3. たとえ誤字でも、既に誰かがその名前に依存していれば変更は破壊的になります。考慮点は「公開後どれだけ経ったか・実利用者がいるか・どれだけ広まったか」です。実質的に誰も使っていない極初期なら同一バージョンで直し、依存者がいるなら新バージョンか、旧名のエイリアス併存で移行期間を設けます。

A4. これは仕様違反のバグ修正で、正しい400を返すのが本来の契約です。原則は同一バージョンで修正してよいですが、誤った200に依存した利用者がいれば壊れる恐れがあります。セマンティックバージョニングでは、観測される振る舞いを変える後方非互換な修正はメジャー、互換を保てるならパッチ相当と判断します（依存実態しだいでメジャー扱いが安全）。

A1. 状態が「有効／削除済み」の2値ならブール（deleted）で十分ですが、「下書き/公開/アーカイブ/削除済み」のように状態が複数あるなら状態フィールド（enumでなく文字列）が適します。両方を持つと「削除済み」を二重に表現でき矛盾の温床になるため、通常は片方に統一すべきで、両立は基本的に意味がありません。

A2. showDeletedのような「既定では隠す対象を見せる」オプションに加え、フィルタ（第22章）でdeleted = trueのように指定して削除済みだけに絞ります。listは既定で削除済みを隠すので、明示的なフラグ/フィルタで対象を切り替えます。

A3. expungeは物理削除なので、論理削除済みかどうかに関わらず実体を完全に消せる設計が一般的です（ごみ箱を経ず直接消す）。一方undeleteは「削除済みを戻す」操作なので、削除されていないリソースに呼んでも何も変わらない（冪等に成功扱い、またはエラー）とします。

A4. 一定の保持期間（例30日）を過ぎたら自動的にexpungeする設計が分かりやすいです。各リソースにexpireTime（いつ完全削除されるか）を持たせて利用者に示し、期限到来で物理削除します。これでごみ箱の自動清掃と、復元可能な猶予を両立できます。

A5. deleteの観測可能な振る舞いが変わらなければ後方互換です。たとえば従来どおり「delete後にgetすると404」を保ったまま内部的に論理削除するなら互換的です。一方、delete後もgetが200を返したり、listの見え方が変わったりするなど、利用者から見える挙動の変化は後方非互換になります。

A1. 内容が同一でも「意図的に2回実行したい」正当な要求（同額の支払いを2回など）まで重複とみなして弾いてしまうからです。だから重複判定はクライアント生成のリクエスト識別子で行い、フィンガープリントはあくまで「同じIDに違う内容が来た」衝突検出の補助に使います。

A2. このキャッシュは「同じリクエストに同じ結果を返す」冪等性が目的で、元リソースの最新値を映す汎用キャッシュではありません。元が変わったからと更新してしまうと、再送に対して初回と違う結果を返し、冪等性が崩れます。だから一定期間は初回の結果をそのまま保持します。

A3. キャッシュ喪失中は重複を検出できないため、再送が二重に実行されかねません。対策としては、キャッシュの永続化・冗長化、ダウン時に安全側へ倒す仕組み、下流での一意制約といった多層防御を組み合わせます。単一のキャッシュに全面依存しない設計が重要です。

A4. リクエストIDはクライアントが生成するため、別内容のリクエストに誤って同じIDを付けてしまう（衝突）可能性があります。フィンガープリントを併せて照合すれば、「同じIDなのに内容が違う」異常を検出してエラーにできます。クライアント生成＝中央で一意性を保証できない、という性質がこの二重照合の必要性を生みます。

A1. 操作ごとに別メソッドを増やすと、本番ロジックと検証ロジックが二重化し、ずれて「検証は通ったのに本番で失敗」が起きます。同じメソッドにvalidateOnlyフラグを足せば、まったく同じ検証経路を通せて予告が正確になり、APIの表面積も小さく保てます。

A2. 副作用を起こさない範囲でのベストエフォートにとどめます。到達性や認可の確認のため通信してよいですが、外部の副作用を起こしてはならず、また外部状態は検証後に変わりうるので「すべては保証できない」と認めます。安全に確認できる部分だけ検証します。

A3. ほとんど意味がありません。読み取り専用の操作はそもそも安全に「試せる」ので、わざわざvalidateOnlyを設ける必要はありません。検証フラグは、実行すると危険な副作用を伴う操作にこそ価値があります。

A4. 既定falseなら、フラグを意識しない普通の呼び出しが本来の実行になり、直感に合います。もし既定true（検証）にすると、利用者が「実行したつもりが何も起きていない」という分かりにくい事故を招きます。purgeのような特に危険な操作を除き、既定を反転させるべきではありません。

A1. 変更のたびに自動で版を残したい場合（ドキュメント編集の履歴のように、すべての変更を追える）は暗黙的が適します。一方、利用者が「ここを確定版にする」「タグを打つ」ような区切りで版を残したい場合は明示的（要求に応じて作成）が適します。粒度と利用者の意図で選びます。

A2. 連番は総数や作成ペースが漏れ、推測で他の版を辿られます。タイムスタンプは同時刻で衝突し、やはり情報が漏れます。ランダムIDなら情報漏れと衝突を避けられ、安全です（識別子の一般原則と同じ、第6章）。

A3. 履歴を追記専用に保つためです。過去の版を直接「現在」に差し替えると履歴が壊れ、監査証跡が失われます。復元は「過去と同じ内容の新リビジョンを作ってアクティブにする」ことで、すべての操作が前向きに記録され、いつでも巻き戻しを追跡できます。

A4. 変更が無いので、新しいリビジョンを作らず何もしない（冪等に成功を返す）のが妥当です。同一内容の版を量産しても無意味なため、「現在と同じならno-op」と扱います。

A5. リビジョンの一覧・削除は、通常のリソース操作とは意味が異なる特別な操作だからです。取得自体は @記法で標準的に行えますが、版の列挙（listRevisions）や特定版の削除（deleteRevision）は履歴という特殊対象への操作なので、標準list/deleteを流用せずカスタムメソッドで明示します。

A1. 同じステータスコードでも、操作が冪等か・どこまで進んだか・副作用があるかで、再送して安全かどうかが変わるからです。たとえばタイムアウトは「届いて処理済みかも」しれず、課金のような非冪等操作では二重実行になりえます。だから一律のルールでは決められず、冪等性やリクエスト識別子（第26章）と併せて判断します。

A2. 失敗直後に連打すると、復旧しかけのサーバーへ負荷が集中して再び落とします。待ち時間を倍々に伸ばす指数バックオフで負荷を逃がします。さらに全クライアントが同じ間隔だと同時刻に殺到（thundering herd）するため、ジッター（ランダムなばらつき）で再試行時刻を散らして同期を崩します。

A3. サーバー側が「いつ再試行すべきか」を知っている場合（レート制限の解除時刻、メンテ明けなど）に意味があります。429や503と共にRetry-Afterを返せば、クライアントは当てずっぽうのバックオフより正確なタイミングで再送でき、無駄な試行を減らせます。

A1. 発信元の証明は「いま受け取ったリクエストが、名乗り通りの送信者から来た」ことの確認です。否認防止は「後から本人が『送っていない』と言い逃れできない」ことの保証で、第三者にも証明できる必要があります。共有秘密などで発信元を確認できても、検証者自身が同じ鍵で偽造できるなら第三者に送信者を立証できず、だから前者だけでは後者を満たせません。

A2. 否認防止が満たされません。サーバーも同じ秘密鍵を持つため、そのサーバーが署名を偽造でき、「本人しか作れない署名」と第三者に示せないからです。発信元と整合性は満たせても、否認防止には本人だけが持つ秘密鍵による公開鍵署名が必要です。

A3. 署名対象がボディだけだと、メソッドやパスを差し替えて同じ署名を悪用できてしまうからです（例同じボディでDELETEに変える、別ホストへ向ける）。メソッド・ホスト・パス・ボディ全体を指紋に含めて署名することで、リクエストのどの部分も改ざんできないようにします。

A4. 受けやすいです。指紋と署名をそのまま捕捉して再送されれば、有効なリクエストとして通ってしまいます。対策として、タイムスタンプやノンス（一度きりの値）を署名対象に含めて有効期間を限定し、サーバー側で使用済みノンスを記録して再利用を拒否します。第26章のリクエスト識別子も二重実行防止に役立ちます。