やったこと

• APIデザインパターン 9章 カスタムメソッド 読了

学んだこと

ポイント

• 標準メソッドとカスタムメソッドの使い分け
• 標準メソッドととカスタムメソッドのどちらの、副作用のある処理を実装するべきか
  • 特に、標準メソッドで副作用のある処理を実装した場合のデメリット

学び

• カスタムメソッドは、標準メソッドの枠に収まらないような、複雑な問題（特に、副作用を持つ処理）を解決する際に使用する
  • 言い換えると、標準メソッドに、副作用を持つ処理を実装するべきではない
• カスタムメソッドには副作用を持つ処理を実装することが多いが、副作用のない処理を実装しても問題ない
• 複数のリソースを扱う際、「コレクションを扱うメソッド」として実装すると良い
  • 「リソースに特化したメソッド」は、将来「単一のリソースを扱う」操作を実装するときのために残しておく

メモ

標準メソッドの枠に収まりきらないような、複雑な問題(特に、何らかの状態管理が必要な、副作用を持つ処理)を解決するAPIを提供する場合に、カスタムメソッドは役立つ。

標準メソッドで副作用を持つ処理を実装することもできるが、以下のデメリットがある。

• クライアント側で状態を指定することになるが、これは正しい状態とは言えない
• 多くの場合 update メソッドを使用することになるが、「データ更新」と「状態遷移」という二つの責務を負うことになる
  • 標準メソッドが責務を二つ持つと、扱いにくいAPIとなってしまい、標準メソッドが掲げる「シンプルさ」を損なうことになる
• 標準メソッドで副作用を扱うことになる
  • 標準メソッドを過度に複雑化する

概要

カスタムメソッドは、（標準メソッドと異なり）制限事項がほとんどない。

• ただし、利用者の理解促進のために、カスタムメソッド全体で一貫性を保つ必要はある
• 言い換えると、ルールを自由に設けることができるが、（一貫性維持のため）設けたルールはカスタムメソッド全体で守ること

実装

カスタムメソッドは、以下の書式で実装する。

POST /book/123456（リソース）:launch（アクション）

• リソースとアクションを: で区切る
  • 大事なのは、リソースとアクションを確実に区別できること
• 多くの場合 POST メソッドで実装する

副作用

カスタムメソッドでは、任意の副作用を実装できる。

• むやみな実装は避ける（≒過度に複雑にするべきではない）
• 副作用を実装する場合、その旨をドキュメントで利用者に説明するべき

複数のリソースを扱う

以下の選択肢を選べる場合、二つ目の選択肢（★）を選ぶと良い（どちらも、複数のEmailをエクスポートすることを想定している）。

• リソースに特化したメソッド ( POST /users/1:exportEmails)
• ★コレクションを操作するメソッド ( POST /users/1/emails:export )

そして、一つ目の選択肢は、将来「単一のリソースを扱う」操作を実装するときのために残しておく。

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

状態を持たず、標準メソッドのどれにも当てはまらないような処理も考えられる。
この場合は、ステートレスのままカスタムメソッドを実装すると良い。

---

扱うこと

• 標準のメソッドではすべてのケースをカバーできないのはなぜか
• 副作用が必要な場合のカスタムメソッドの使用
• 計算に特化したAPIメソッドでステートレスのカスタムメソッドを使用する方法
• カスタムメソッドのターゲット（リソースかコレクション）を決める

まとめ

• カスタムメソッドは、ほとんどの場合、HTTP POST メソッドで実装する
  • PATCH メソッドで実装するべきではない
  • 冪等性をもち、安全な場合はGETを使用することもある
• カスタムメソッドでは、コロン（:）を使ってリソースのターゲットと実行するアクションを分離する
  • /missiles/1234:launch など
• カスタムメソッドでは、副作用を取り扱うことが出来る
  • 標準メソッドではダメ
    
  • 副作用の利用は計画的に、ドキュメントによる説明も行うこと
• 一般的に、カスタムメソッドが一つのコレクション内の複数のリソースを対象とする場合は、コレクションを丸ごと扱うこと
• ステートレスなカスタムメソッドで処理を実行するかは、よく検討すること
  • 後からステートフルに変更する可能性は常に存在する
  • そして、後からステートフルへ変更することはそれなりに大変