やったこと

• API デザインパターン 20章 匿名書き込み 読了

学んだこと

ポイント

ポイント

• 標準のcreateメソッドと比較した、writeメソッドの特徴
• writeメソッドの実装が効果的なユースケース

• writeメソッドで書きこむデータに対する、一貫性の考え方

  学び

• writeカスタムメソッドは、一意の識別子を持たない（≒持たせることに意味のない）データを書き込むためのメソッド

• writeメソッドは、集計値にこそ価値があるデータをAPIで書き込みたい場合に有効

  • 個々のデータを識別したい場合は、標準の create メソッドを通して、リソースとして扱う

• writeメソッドで一貫性を保つことに、あまり意味はない

メモ

データを特定できないような、「書き込み」に特化した処理は、そのままではリソース指向には向かない。

• ログデータなど、非常に小さな単位での書き込み処理が該当

そのため、「書き込み処理」という独自の概念を組み入れて、非リソース指向のデータを、リソース指向に適合させる。

ここでいう「匿名データ」とは、識別子を持たないデータを指す。

概要

以下の特徴を持つ、 write カスタムメソッドを実装する。

• 匿名のまま（≒一意な識別子を持たせず）書き込み可能
• 書き込んだデータ群に対して、集計値を要求できる
  • そして、個々のデータを取り出すことはできない

writeカスタムメソッドにて書き込むデータを、 リソースと区別して エントリー と呼称する。

実装

writeカスタムメソッドでは、以下のように振る舞う。

• 書き込みに成功した場合は、値を何も返さない（またはvoidを返却する）
• 書き込みに失敗した場合は、エラーを返す

URLは、以下を推奨（議論の余地あり）。

/chatRooms/1/statEntries:write

一貫性

読み込みについて、一貫性を維持することはあまり重要ではない。

• get 処理では 統計データを返すため、どのデータを追加したか知る意味が薄い
• 他の誰かが writeメソッドを呼んでいる可能性

そのため、writeメソッドは、バックエンドの処理を待たずに、 200 OKを返してよい。

• LRO（Long Run Operation）を返すのもNG
• 結果に時間がかかる場合は、 202 Accepted を返すだけで十分

トレードオフ

write メソッドは、分析用データやログデータなど、以下のような状況でのみ役立つ。

• 識別子を持たせることにあまり意味がない
• 個々のデータではなく、分析結果に価値がある

また、そもそも分析データの取り込みを、APIでサポートするべきかも、議論のポイント。

扱うこと

• 匿名データとは何か
• リソースの作成に頼らず、APIに伝田を取り込む方法
• 取り込んだデータの一貫性に関する問題にどう対処するか

まとめ

• データをシステムに取り込む必要がある場合、専用の writeメソッドを使用する
  • 言い換えると、アドレス指定されない、個別のリソースを作成したりしない
• writeメソッドでAPIに書き込んだデータは、後でAPIから削除できない
• writeメソッド（およびそのバッチ版）は、結果のステータスコード以外のレスポンスは返さない
  • 特殊な状況を除いて、LROリソースであってもリソースを返してはならない
• writeメソッドは、リソースではなく、エントリーを扱う
  • エントリーは、アドレス指定できない、一時的なデータのこと