API設計

APIバージョニング えーぴーあいばーじょにんぐ

APIバージョン管理後方互換性RESTful APIエンドポイント破壊的変更
APIバージョニングについて教えて

簡単に言うとこんな感じ!

APIに「v1」「v2」みたいなバージョン番号をつけて管理する仕組みだよ。アプリを壊さずにAPIをアップデートできるようにする工夫で、古いバージョンを使い続けたい人と新機能を使いたい人の両方に対応できるってこと!


APIバージョニングとは

APIバージョニングとは、APIに「バージョン番号」を付けて管理する設計手法のことです。システム間の通信に使うAPIは、リリース後もたびたび改修が必要になりますが、変更のたびに既存のアプリが壊れてしまっては困ります。そこで「古い仕様のv1」と「新しい仕様のv2」を並行して運用し、利用者が自分のペースで移行できるようにする、というのがバージョニングの本質です。

特にビジネスシーンでは、スマホアプリや外部パートナーのシステムが自社のAPIを呼び出すケースが多くあります。こうした外部連携が増えると、「APIを変えたら取引先のシステムが動かなくなった」という問題が起きがちです。APIバージョニングはその防波堤になる設計思想で、後方互換性(古い仕様でも動き続ける性質)を保ちながら進化できる仕組みを提供します。

発注側・選定側の視点では「ベンダーが提供するAPIにバージョン管理の方針があるか」を確認することが重要です。バージョン管理の方針がないAPIは、突然の仕様変更で自社システムに影響が出るリスクがあります。


バージョニングの方式と比較

代表的なバージョニングの実装方法は4種類あります。それぞれ一長一短があるため、システムの用途や規模に応じて選択します。

方式例特徴主な用途
URLパス方式/api/v1/users見た目でわかりやすい。キャッシュが効きやすい最も広く使われる
クエリパラメータ方式/api/users?version=1URLの変更が最小限簡易的な実装に
HTTPヘッダー方式Accept-Version: 1.0URLをすっきり保てる企業向けAPIに多い
メディアタイプ方式Accept: application/vnd.myapp.v1+jsonRESTの原則に忠実高度なAPI設計向け

「v」の付け方のルール

バージョン番号は セマンティックバージョニング(MAJOR.MINOR.PATCH の形式)の考え方を参考にすることが多いです。APIでは特に「破壊的変更(後方互換性を壊す変更)」があった場合にメジャーバージョン(v1→v2)を上げる、というルールが一般的です。

  • 破壊的変更の例:レスポンスのフィールド名変更、必須パラメータの追加、エンドポイントの削除
  • 非破壊的変更の例:新しいフィールドの追加、新しいエンドポイントの追加

覚え方

「壊れたらv上げる」──後方互換を壊す(=古いアプリが動かなくなる)変更をしたときだけ、メジャーバージョンを上げると覚えておくと実務でも判断しやすいですよ。


歴史と背景

  • 2000年代前半:SOAPベースのWebサービスが主流。WSDLという定義ファイルでバージョン管理していたが、複雑で扱いにくかった
  • 2000年: Roy Fieldingが博士論文でRESTアーキテクチャを提唱。シンプルなHTTP APIの普及が始まる
  • 2000年代後半〜2010年代:Twitter・Stripe・Twilio などがREST APIを公開。/v1/ をURLに含める「URLパス方式」が事実上の標準として広まる
  • 2012年頃〜:モバイルアプリの爆発的普及により、「古いアプリを使い続けるユーザー」への対応が必須に。バージョニング戦略の重要性が一気に高まる
  • 2015年頃〜:GraphQLの登場により「バージョニング不要」な設計アプローチも注目される。ただしREST APIの主流は変わらず並存している
  • 現在:OpenAPI(Swagger)などの仕様書ツールでバージョン管理を文書化するのが業界標準になっている

バージョン戦略の全体像

URLパス方式を例に、v1とv2が並行運用される構造を図解します。

APIバージョニング(URLパス方式)の全体像 スマホアプリ (古いバージョン) スマホアプリ (新しいバージョン) パートナー企業 のシステム GET /api/v1/users 旧バージョンのエンドポイント GET /api/v2/users 新バージョンのエンドポイント v1ロジック 旧仕様で処理 v2ロジック 新仕様で処理 APIサーバー(バックエンド) v1・v2を同時に受け付け、それぞれ適切なロジックへルーティング

非推奨(Deprecated)化の流れ

バージョンを上げたからといっていきなり古いバージョンを廃止するのは禁物です。一般的なライフサイクルは以下の通りです。

v1リリース
    ↓(機能追加・破壊的変更が必要に)
v2リリース ← v1は引き続き利用可能
    ↓(移行期間を設ける。通常6か月〜2年)
v1を「非推奨(Deprecated)」に指定 ← レスポンスヘッダーなどで警告
    ↓
v1のサポート終了(EOL: End of Life)

廃止スケジュールを事前に告知することが、利用者との信頼関係を守る最重要ポイントです。


関連する規格・RFC

規格・RFC番号内容
RFC 9110HTTP Semantics(HTTPの意味論を定義。APIのベースとなるHTTPの仕様)
RFC 7231HTTP/1.1: Semantics and Content(Acceptヘッダーなどメディアタイプ方式に関連)
RFC 8594The Sunset HTTP Header Field(APIの廃止予告をヘッダーで通知する標準仕様)

関連用語

  • REST API — HTTPをベースにしたAPI設計スタイル。バージョニングの文脈で最もよく使われる
  • OpenAPI — APIの仕様をYAML/JSONで記述する標準フォーマット。バージョン情報も記載できる
  • セマンティックバージョニング — MAJOR.MINOR.PATCH 形式でバージョン番号を管理するルール
  • 後方互換性 — 古い仕様でも動き続けることができる性質
  • GraphQL — Facebookが開発したAPIクエリ言語。「バージョニング不要」を特徴の一つとする
  • エンドポイント — APIにアクセスするためのURL。バージョニングでは /v1/users のように記述する
  • Webhook — サーバーからクライアントへのプッシュ型API通知。バージョン管理の対象になることも多い
  • API Gateway — APIへのリクエストを一元管理するミドルウェア。バージョンごとのルーティングを担う

シス担のミカタ メールマガジン

セキュリティの速報とシステムの最新情報をメールで受け取る

登録すると、次の配信からお届けします。配信はメールの下のリンクから、いつでも解除できます。個人情報の取り扱い