REST APIでの通貨コードの使用
REST APIで通貨と金額を表現するベストプラクティス。JSONフォーマット、ISO 4217の使用法、補助単位パターン、一般的なAPI設計ミスを解説。
Development
詳細な説明
API設計における通貨コード
金額を扱うREST APIを設計する際、通貨の一貫した曖昧でない表現が重要です。ISO 4217コードの使用が業界標準ですが、APIペイロードでの金額と通貨の構造化方法は異なります。
一般的なJSONパターン
パターン1：金額と通貨フィールドの分離
{
"amount": 29.99,
"currency": "USD"
}
シンプルですが浮動小数点精度の問題が発生しやすい。
パターン2：補助単位での金額（推奨）
{
"amount": 2999,
"currency": "USD"
}
Stripe、PayPalなどの主要決済プロセッサーがこのパターンを使用。金額は最小通貨単位（USDのセント、JPYの円）で表されます。浮動小数点の問題を完全に回避。
ベストプラクティス
- 常に通貨コードを含める — USDやデフォルトを仮定しない
- ISO 4217アルファベットコードを使用 — "USD"であって"usd"、"$"、"dollar"ではない
- 単位規約を文書化 — 金額が主単位（29.99）か補助単位（2999）かを明確に記述
- 一貫性を保つ — エンドポイント間でパターンを混在させない
ゼロ小数通貨
JPY、KRWなどのゼロ小数通貨では、補助単位は主単位そのものです：
{ "amount": 1000, "currency": "JPY" }
// これは1000円を意味し、10.00円ではない！
ユースケース
決済システム、ECプラットフォーム、または金融APIを構築するAPI設計者やバックエンド開発者は、金額の適切な表現方法を選択する必要があります。補助単位パターン（StripeやPayPalが使用）は、浮動小数点の問題を排除しつつ言語非依存であるため、業界標準となっています。