API設計原則

エンドポイント設計:

• GET /v1/projects/{projectId}/tasks?status=open&sort=-createdAt&page=1&limit=20
• POST /v1/projects/{projectId}/tasks — タスク作成
• PATCH /v1/tasks/{taskId} — タスクの一部更新

成功レスポンス例:

{
  "data": [
    { "id": "t-001", "title": "API設計書を書く", "status": "open" }
  ],
  "meta": { "total": 42, "page": 1, "limit": 20 }
}

エラーレスポンス例:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "タスクが見つかりません",
    "details": [{ "field": "taskId", "value": "t-999" }]
  }
}

フロントエンドはdataとerrorの2パターンだけハンドリングすればよく、エラー処理コードが従来の1/3に削減された。

状況: 5名のバックエンドチームが、各自の好みでAPI設計をしていた。レスポンス形式が3パターン混在し、フロントエンドチームがエンドポイントごとにパーサーを書いていた。

施策:

1. 1ページのAPIスタイルガイドを作成（命名規則、レスポンス形式、ステータスコード一覧）
2. PRテンプレートに「APIスタイルガイド準拠チェック」を追加
3. 既存APIのうちアクセス頻度上位10エンドポイントを新形式に移行

1ページのスタイルガイドがチーム全体の「迷い」を解消した。APIレビューの指摘事項は月42件→12件に減少し、新エンドポイントの結合工数は平均3日→1日に短縮された。

状況: 外部パートナー向けAPI。ドキュメントが古く、エラーメッセージが内部コード（ERR_0042）のままで、パートナーからの問い合わせが月80件。

施策:

1. OpenAPI 3.0でスキーマを再定義し、Swagger UIで公開
2. エラーコードを人間が読めるものに変更（INVALID_EMAIL、RATE_LIMIT_EXCEEDED）
3. サンドボックス環境を提供し、本番データなしでテスト可能に

パートナーからの問い合わせが月80件→15件に減少し、新規パートナーの連携開発期間が平均4週間→10日に短縮。API呼び出し数は月間50万→150万に増加し、間接的にARRが12%向上した。