ウェブAPIのエラーをどう伝えるか

ウェブAPIにおいて下記はよくある状況だと思う。

• エラーの伝達先が複数ある
  • APIの提供者
  • APIの利用者
• エラーの伝達先によって伝達手段が異なる
  • 伝達先: APIの提供者 → 伝達手段: ログ
  • 伝達先: APIの利用者 → 伝達手段: レスポンス

ここでログの方は出力タイミングについて考える余地がある。内側(エラーの発生箇所)で出力すべきか外側(レスポンスを返す箇所)で出力すべきかだ。おそらく無難なのは外側の方だろう。

As a rule of thumb,

errors should be logged when they are handled.

If your function is propagating the error upstream (e.g. using the ? operator), it should not log the error. It can, if it makes sense, add more context to it.

Who Should Log Errors? (Error Handling In Rust - A Deep Dive)

では伝達内容についてはどうだろうか。内容として必要なのは伝えられた側が次の行動を決めるための情報だろう。これはAPIの提供者と利用者で必ずしも一致しない。かといって和集合を取るわけにもいかない。API提供者用の情報をAPI利用者へ渡すのには懸念があるからだ。

• 攻撃の手掛かりになり得る
• 内容を理解可能とは限らない
  • 例えばライブラリ内部のエラーをそのまま見せられても、それが何を意味するかやどんな対処をすべきか分かるとは限らない
  • サポートのコスト増加に繋がる恐れがある

つまり伝達先によって伝達手段だけでなく伝達内容も変える必要がある。単純に書いてしまうなら下記のようになるだろうか。

では何が最小限かというところに絡めてエラーコードについても書きたいが今日はここまで。