APIの応答に操作へのリンクが含まれていると、そのリンクをケイパビリティと呼びたくなる。 しかし、操作を発見するための情報と、その操作を実行する権限は区別しなければならない。
アフォーダンスは、現在の対象に何ができるかを利用者やクライアントへ示す。 注文の応答に payment というリンクがあれば、支払いへ進めることを発見できる。 これは状態に応じて可能な操作を返すAPIが提供する制御情報である。
ケイパビリティは、特定の対象を指定し、その対象へ作用する権限も伴う偽造不能な参照である。 ケイパビリティを保持するコードは参照先の操作を実行でき、持たないコードは実行できない。 対象の指定と権限の検査が一つの参照に結び付いている。
たとえば次のURLは、支払いというアフォーダンスを示しても、それだけではケイパビリティにならない。
/orders/42/payments誰でもURLを推測でき、サーバーが別途ログイン情報から認可するなら、このURLは対象を指定する識別子にすぎない。 十分にランダムな秘密URLを受け取った者だけが支払えるなら、そのURLは所持によって権限を与えるCapability URLになる。
この区別をしないと、操作リンクを返しただけのAPIに、最小権限や安全な委譲まで実現したかのような説明を与えてしまう。 アフォーダンスは発見可能性を改善し、ケイパビリティは権限の到達範囲を制限する。 同じリンクが両方を担うことはできるが、その場合は秘密情報としての管理と失効が必要になる。
https://koriym.github.io/blog/2025/03/31/cubist-coding/
https://www.erights.org/elang/kernel/auditors/index.html
https://www.w3.org/TR/capability-urls/
#api-design #affordance #capability #security #authorization