やったこと

API デザインパターン 7章 標準メソッド 読了

学んだこと

ポイント

• 冪等性/副作用
• 標準的なメソッド
• うまく設計されたAPIとは
• 標準化のトレードオフ

学び

• うまく設計された API は、一貫性があり、予測可能で扱いやすい
• 使用していないHTTPメソッドへのリクエストには、 405 を返すと良い
• 標準的な処理を整理すると、 Get , List , Create , Update , Delete , Replace の6つに分類できる
• Replace メソッドでは、新規作成を請け負わない方が良い
• 標準的なメソッドは一貫性を持つべき
  • 結果整合性を持つデータを扱う場合、カスタムメソッドの実装を検討すること
• 標準的なメソッドを用いるという事は、柔軟性と学習コストのトレードオフ
  • 基本は標準的なメソッド、標準的なメソッドで賄いきれない部分はカスタムメソッドを実装する

気づき

• この章の文脈における「標準」は「汎用」ぐらいに思っておく
  • 「カスタムメソッド」は「特化メソッド」ぐらいに思っておく

メモ

うまく設計された API は、一貫性があり、予測可能で扱いやすい。

実装

どのメソッドをサポートするべきか？

使用していないメソッドで通信を試みると、404が返ってくる。
これでは、リソースが存在しないのか、メソッドがサポートされていないのか、利用者が判別できない。
利用者がこれらを判別できるよう、正当な理由がない限り、各リソース毎に、標準メソッドを実装する。

• そして、使用しない理由をドキュメントで説明する
• 使用しないメソッドは 405 Method Not Allowedや403 を返す

書籍では、標準的なメソッドとして Get , List , Create , Update , Delete , Replace を挙げている。

• 状況標準メソッドを、HTTPメソッドにて実装していく
  • 上記標準メソッドと同じ名前のHTTPメソッドを作れ、というわけではない

冪等性と副作用

標準メソッドが予測可能であるために、可能な限り副作用をもたないようにする。
メソッド次第では冪等性も満たすべき。
副作用を持たせるか、冪等性を持たせるかの判断は、場合による。

Get

識別子を受け取り、それに合致するリソース1つだけを返却する。

冪等性 ... 満たすべき
副作用 ... 顕著な副作用（※）があってはならない

（※）顕著な副作用
稼働しているアプリケーションの動作に影響があるような副作用。
顕著ではない副作用としては、メソッド呼び出し回数を記録するカウンタの更新など

List

特定の条件に合致したリソースのコレクションを返却する。
返却するコレクションは、「すべてのデータが揃った具体的なリソース」である必要はない。

• 恐らく、「条件を満たすリソースの識別子」など、リソースの一部分だけを抽出したコレクションでも良い、と言いたいのだと解釈
• 予測可能性を下げそうな気がする

Create

与えられた情報を基に、API内に新しいリソースを作成するメソッド。
その後、レスポンスとして、作成したリソースを返却する。

作成した情報は即座に読み取ることが出来るべき（書籍では、一貫性と表現している）。
結果整合性を持つデータは、一貫性を満たさない。
標準メソッドは一貫性を満たしていることが期待される。
もし一貫性を満たさないデータを取り扱いたい場合は、カスタムメソッドにて取り扱うと良い。

Update

与えられた情報を基に、リソースを更新する。
その後、レスポンスとして、、更新後のリソースを返却する。

一部分を更新する際は PATCH メソッドを使用する。
全部更新する（もはや置き換え）際は PUT メソッドを使用する。

Update ではなく、カスタムメソッドを使用した方が良い場合もある。

• 更新処理で状態遷移を表現したい場合など
• どういった状態へ変更するのかがひと目でわかる名前のカスタムメソッドの方が良い

Update以外にも、更新処理があっても問題ない。

Delete

与えられた情報を基に、リソースを削除する。
戻り値は無い。

Deleteの戦略には、動作重視と結果重視が存在する。

◇動作重視
「リソースの削除処理に成功した」ことを重視する。
削除対象のリソースが存在しない、「削除する処理」を実行できず、エラーとなる。
例として、同じIDに対してDeleteを二回連続で要求すると、二回目はエラーとなる。
このため、動作重視の戦略では、冪等性は満たしていない。

◇結果重視
「リソースが存在しなくなっている」状態であることを重視する。
たとえ削除対象のリソースが存在しなくても、「指定したリソースが存在しない」状態は達成できているので、Delete成功とみなす。
こちらの場合、冪等性は満たしている。

Replace

与えられた情報を基に、リソース全体を置き換える。

HTTP の PUTで実装する。
新規リソースの作成も担うことが出来るが、その場合、識別子問題が発生する。

◇識別子問題
リソースを新規作成したい場合は、クライアント側で識別子を作成できる必要がある。
そして、クライアント側では識別子を作成できない方が良い。
このため、要件上必要な場合を除き、一般的なユースケースでは新規作成を担わなない方が良い。

トレードオフ

標準化された仕組みを利用することは、以下のトレードオフである

• 既存の仕組みに縛られるため、柔軟性が低下する
• 利用者が、「既存の仕組み」を既に知っている場合、学習コストが低くなる

標準メソッドは、あらゆる状況に対応できるわけはない。
その代わり、API利用者は、少ない学習でAPIを習得できる。

標準メソッドではどうしても賄いきれない処理は、カスタムメソッドを実装する。

---

取り扱うこと

• 冪等性とその副作用
• 標準メソッドの紹介
• 準標準メソッド
• 標準メソッドの利点と欠点

まとめ

• 標準メソッドを用いることで、APIは一貫性と予測可能性を高めることが出来る
• すべての標準メソッドが同じ動作原則に従うことが重要
  • 例) すべての putメソッドは、同じように動作するべき
• 冪等性とは、メソッドを何回呼び出しても、常に同じ結果になるという特性
  • APIシステムのどこかに変更が生じるような副作用は持つべきではない
  • deleteメソッドは冪等性を満たさない
• 標準メソッドは、できることがある程度決まっている
  • 一方で、API利用者は、リソース指向APIに関する既存の知識を活用しやすい（つまり、学習コストが低い）