← 戻る

API⇔CLIのレスポンス形式不一致でハマるパターン

api-design rust serde debugging

問題

REST APIとRust CLIを別々に開発すると、レスポンスのJSON構造が噛み合わなくなる。

典型的な不一致パターン:

API が返すCLI が期待するエラー
[{...}] (配列直接){ "items": [{...}] } (ラップ)invalid type: map, expected a sequence
{ "success": true }{ "message": "..." }missing field 'message'
{ "id", "name", "extra_field" }{ "id", "name" } (フィールド不足)missing field 'extra_field' ではなく別のエラー

対策

  1. APIレスポンスは常にオブジェクトでラップする（{ tasks: [...] } 形式）。拡張性も高い
  2. Rust側のデシリアライズ構造体は、APIが返す全フィールドを網羅するか、#[serde(deny_unknown_fields)] を付けない（デフォルトで未知フィールドは無視される）
  3. API仕様を先に決めてから両方実装する。OpenAPI等で契約を明文化するのがベスト