api-versioning-strategy

API バージョニング戦略

適切な廃止までの期間を設定し、API のバージョニング方式を選択して実装します。

バージョニング方式

方式	例	メリット	デメリット
URL パス	/api/v1/users	明確で、キャッシュに適しています	URL が煩雑になります
ヘッダー	API-Version: 1	URL がすっきりします	見えにくく、テストが難しくなります
クエリ	?version=1	簡単に使用できます	RESTful ではありません

URL パスによるバージョニング（推奨）

const v1Router = require('./routes/v1');
const v2Router = require('./routes/v2');

app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

バージョンアダプターパターン

// Transform between versions
const v1ToV2 = (v1Response) => ({
  data: {
    type: 'user',
    id: v1Response.user_id,
    attributes: {
      name: v1Response.user_name,
      email: v1Response.email
    }
  }
});

廃止を示すヘッダー

app.use('/api/v1', (req, res, next) => {
  res.setHeader('Deprecation', 'true');
  res.setHeader('Sunset', 'Sat, 01 Jun 2025 00:00:00 GMT');
  res.setHeader('Link', '</api/v2>; rel="successor-version"');
  next();
});

互換性のある変更と破壊的変更

互換性のある変更（バージョンを上げる必要はありません）：

• 任意フィールドの追加
• 新しいエンドポイントの追加
• 任意パラメーターの追加

破壊的変更（新しいバージョンが必要です）：

• フィールドの削除
• フィールド型の変更
• レスポンス構造の再編成
• エンドポイントの削除

廃止までのタイムライン

フェーズ	期間	対応
廃止予定	3 か月	ヘッダーとドキュメントを追加
サンセット告知	3 か月	ユーザーにメールを送信
読み取り専用	1 か月	書き込みを無効化
シャットダウン	-	410 Gone を返す

ベストプラクティス

• 最低でも N-1 バージョンをサポートします
• 6 か月以上の移行期間を設けます
• コード例を含む移行ガイドを用意します
• バージョンの利用状況を監視し、廃止の判断に役立てます