API 設計の基本

API とは「使い方の約束」

API（Application Programming Interface）は、あるソフトウェアの機能を外から呼び出すための約束ごとです。利用者は内部の作りを知らなくても、決められた入口（関数・エンドポイント）を通じて機能を使えます。家電のリモコンに例えるなら、ボタンの配置と役割が API、内部の電子回路が実装にあたります。

• 隠蔽 — 内部の複雑さを隠し、利用者には必要な操作だけを見せます。
• 契約 — 「この入力を渡せば、この出力が返る」という取り決めです。
• 境界 — ライブラリ・サービス・モジュールの間の接点として機能します。

ライブラリの公開関数、Web の REST/GraphQL エンドポイント、OS のシステムコールなど、形はさまざまですが「実装を隠し、約束された操作だけを公開する」という本質は共通です。設計の良し悪しは、利用者がどれだけ迷わず・安全に使えるかで決まります。

使いやすい API の原則

優れた API には共通する性質があります。中でも重要なのは、学ばなくても推測できること、そして全体が一貫していることです。

• 直感的な命名 — getUserById のように、名前から動作が読み取れること。
• 一貫性 — 似た操作は似た形にする。getUser があるなら getOrder も同じ流儀で。
• 最小限の公開 — 公開する面を小さく保つ。一度出すと撤回が難しいためです。
• 予測可能性 — 同じ入力には同じ結果。隠れた副作用で利用者を驚かせないこと。

// 一貫性のない例：命名も引数順もバラバラで覚えられない
fetchUser(id);
order_get(orderId);
deleteItemById(id, true);

// 一貫した例：動詞＋対象、引数の並びも揃っている
getUser(userId);
getOrder(orderId);
deleteItem(itemId, { force: true });

エラー設計

正常系だけでなく、失敗をどう伝えるかが API の使い勝手を大きく左右します。エラーは「利用者が次に何をすべきか」を判断できる形で返すのが理想です。

• 何が起きたかを区別できる — 「不正な入力」と「権限がない」と「サーバー障害」は別物として伝えます。
• 一貫した形 — エラーの構造（コード・メッセージ・詳細）を全体でそろえます。
• 行動可能な情報 — 「失敗しました」ではなく、原因と対処の手がかりを含めます。

Web API では、HTTP ステータスコードで大分類を表すのが定石です。

種類	例	意味
2xx	200, 201	成功
4xx	400, 401, 404	利用者側の誤り（入力・認証・不在）
5xx	500, 503	サーバー側の障害

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "メールアドレスの形式が正しくありません",
    "field": "email"
  }
}

このように機械が判別できるコードと人が読めるメッセージを分けて返すと、呼び出し側が分岐処理も表示もしやすくなります。

後方互換とバージョニング

API がいったん公開されると、その先には自分が把握しきれない利用者がいます。安易に仕様を変えれば、彼らのコードが一斉に壊れます。だからこそ**後方互換性（backward compatibility）**の維持が最優先になります。

変更の種類	例	互換性
安全な変更	任意フィールドの追加、新エンドポイント	壊れない
破壊的変更	フィールド削除、引数の意味変更、必須化	壊れる

避けられない破壊的変更が必要になったら、古い版を残したまま新しい版を並走させるバージョニングで段階的に移行します。URL に含める方式（/v1/users、/v2/users）が広く使われます。

まとめ

API は、実装を隠して必要な操作だけを公開する「使い方の約束」です。使いやすさの核心は、推測できる命名と全体を貫く一貫性、そして利用者を驚かせない予測可能性にあります。失敗の伝え方を整えるエラー設計も体験を大きく左右します。さらに、一度公開した契約を壊さない後方互換を最優先とし、避けられない変更はバージョニングで段階移行する——これらを守ることで、長く信頼される API になります。