API設計入門｜半年後の自分が最初の利用者——「驚かせないAPI」の作り方

「驚かせない」が最上位の設計目標——Googleが文書化した理由

APIの価値は呼び出し側の学習コストの低さで決まる。一貫性は美学ではなく、ドキュメントと問い合わせを減らす実利。

API設計の参考書として最も実務的なのが、Googleが公開しているAIPです。自己定義は“a design document providing high-level, concise documentation for API development”——API開発のための簡潔な設計文書群。膨大な自社APIの一貫性を保つための社内標準を、そのまま外部に公開したものです。

なぜ巨大企業ほど「一貫性」に投資するのか

理由は単純で、APIの利用コストの大半は学習コストだからです。1つのAPIで覚えた規則が他のAPIでも通用すれば、利用者は推測で正解できます。逆に命名やエラー形式がAPIごとに違えば、その差分のぶんだけドキュメントと問い合わせが増える。個人開発でも構図は同じで、利用者第1号は半年後の自分です。

土台はリソース指向——名詞に寄せる

エラーとページネーション——利用者が最初に触る2つの品質

利用者はハッピーパスよりエラーとの付き合いでAPIの質を判定する。エラーの2層構造と一覧の上限は、最初の実装に含める。

API設計の品質が最も露呈するのは、正常系ではなくエラーの返し方です。呼び出し側はエラーを見て分岐を書くため、エラーの形が不安定なAPIは自動化に組み込めません。

エラーは「機械向け＋人間向け」の2層で

// ❌ これでは呼び出し側は文字列マッチで分岐するしかない
{ "error": "なんかおかしいです" }

// ✅ codeで機械が分岐し、messageで人間が理解する
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "email の形式が正しくありません"
  }
}

コードは一度公開したら変えない安定した語彙にし、メッセージは自由に改善する——この分離が2層構造の狙いです。なお内部のスタックトレースやSQL断片をレスポンスに含めるのはセキュリティ上の情報漏えいなので、本番では返しません。

一覧APIには最初から上限を

「全件返す一覧API」は、データが増えた日に時限爆弾になります。一覧系には1ページの件数上限と、次ページの取得手段を最初から入れます。limitに上限を設けるのは、呼び出しミスや悪意ある大量取得からDBを守るレート制限と同種の防御でもあります（API連携の記事の上限の話の、提供者側の視点です）。

一番の事故は「黙って壊す」——互換性という約束

フィールド追加は安全、削除・改名・型変更は破壊。破壊するときだけバージョンを上げ、旧版に猶予を与える。この2行が互換性運用のすべて。

API設計の事故で最も恨まれるのが、既存の呼び出しを黙って壊す変更です。自分しか使っていないつもりのAPIでも、自動化ワークフローや別プロジェクトの自分が呼んでいることは珍しくありません。

壊す変更・壊さない変更の仕分け

個人開発のバージョン運用は「/v1/と猶予」だけでいい

凝ったバージョン戦略は不要です。URLに/v1/を入れておき、破壊的変更が必要になったら/v2/を並行稼働させ、旧版は告知して一定期間後に閉じる——これだけです。大事なのは仕組みより「壊すときは必ず新しい番号で」という約束を自分に課すこと。約束が守られているAPIは、外部公開したときそのまま商品品質になります。