invoices.create の名前を確定・請求発行という効果に見合うものにするか決める

[reiroop]

背景

invoices.create は Invoice を作成するだけでなく、価格を項目として追加し、確定(finalize)して、支払い可能な Invoice(Stripe がホストする支払い URL)を発行する。

問題

エンドポイント名の create は、下書きを作るだけのような無害な操作に読める。実際にはこの操作が、確定済みで支払い可能な Invoice という金銭的な請求を生む点が名前から伝わりにくい。認可(#15)を導入した後も、危険度の高い操作であることが API の名前(インターフェース)に表れている方が誤用を防ぎやすい。

やること

• create のままにするか、確定・発行という効果が伝わる名前(例: issue)へ変えるかを決める
• 変える場合は契約・実装・テスト・(将来の)クライアント利用箇所を更新する

受け入れ条件

• エンドポイント名が実際の効果と釣り合っていること、または現状維持の判断が根拠とともに残っていること

関連

#15(認可)における変更系エンドポイントの危険度管理と関わる。また同じ invoices.create の未決定事項として #19(請求書メール送信フロー)がある。