APIバージョニング

APIバージョニングとは？

APIバージョニングとは、APIに対する変更を管理・追跡するプロセスであり、あわせてそれらの変更をAPIの利用者に伝えることも含まれます。

API開発において、変更は避けられない自然な要素です。たとえば、セキュリティの脆弱性を修正するためにコードを更新する必要が生じたり、新機能や拡張を追加したりすることがあります。中には利用者にまったく影響を与えない変更もありますが、「破壊的変更（breaking changes）」と呼ばれる後方互換性のない変更によって、予期せぬエラーやデータ破損などが発生することもあります。APIバージョニングは、こうした変更を安全かつ効果的に展開し、APIのセキュリティ、安定性、パフォーマンスを維持しながら、利用者の信頼を損なわないようにするための重要な手段です。

ここでは、APIバージョニングの主な利点と、それが必要となる代表的なシナリオを紹介します。また、一般的なバージョニング手法、APIを正しくバージョニングするための5つのステップ、ベストプラクティスについても取り上げます。最後に、Postman APIプラットフォームがAPIバージョニングのワークフローをどのように支援できるかをご紹介します。

APIバージョニングの利点とは？

APIがプライベートであってもパブリックであっても、提供者と利用者がAPIの進化にあわせて常に同期を保つことは非常に重要です。効果的なAPIバージョニング戦略は、破壊的変更による利用者への影響を最小限に抑えながら、提供者が継続的に改善を進められるようにします。また、こうした変更を利用者にわかりやすく伝えるための仕組みも提供します。このような透明性は、利用者との信頼関係を築くうえで欠かせない要素です。特に公開APIにおいては、組織の信頼性や評判を高め、APIの採用率および継続利用率の向上にもつながります。

いつAPIをバージョニングすべきか？

APIに変更を加えることで、利用者側でコードベースの修正が必要になる場合、その変更は「破壊的変更（breaking changes）」とみなされ、APIのバージョニングが必要です。このような破壊的変更は、APIの入力・出力データ構造、成功・エラー時のレスポンス、セキュリティ機構などに関わる場合があります。たとえば、プロパティ名の変更、必須パラメータの追加、データ形式の変更などが該当します。

• プロパティやエンドポイントの名前変更：プロパティやメソッドの意味をより明確にするために、その名前を変更したくなる場合があります。明確な命名はAPI設計において重要ですが、本番環境で公開されたAPIでは、こうした名前の変更を利用者のコードに影響を与えずに行うのはほぼ不可能です。
• オプションパラメータを必須パラメータに変更：APIの進化に伴い、最初はオプションとして設計された入力パラメータが、実際には必須であるべきと判断されることがあります。このような変更は、入力の標準化やAPI操作の予測可能性の向上に役立つ一方で、値の送信を前提としていないクライアントでは、プロパティ不足によるエラーを引き起こす可能性があります。
• データ形式やタイプの変更：たとえば、firstNameやlastNameなどの複数のプロパティは、それぞれ文字列として個別に定義するのではなく、userオブジェクトの内部プロパティとしてまとめるべきだと判断されることがあります。このような変更はAPI設計の改善につながりますが、破壊的変更であることに変わりはなく、クライアント側でのパース処理中に例外が発生する可能性があります。
• プロパティの特性の変更：一部のプロパティに対して、設定されている制約ルールを変更したくなる場合もあるでしょう。たとえば、type: stringのdescriptionという文字列型プロパティに対して、maxLengthの値が、実際には短すぎたり長すぎたりすることに気づくケースがあります。このような変更は、実装の仕方によっては、データベースやUI側でのエラーを引き起こす可能性があります。

APIバージョニングの種類とは？

APIバージョニングには、以下のような複数のアプローチがあります。

• URLバージョニング：この方式では、バージョン番号をAPIエンドポイントのURLに含めます。たとえば、データベース内のすべての製品情報を取得したい場合、利用者はhttps://example-api.com/v1/productsにリクエストを送信します。これは最も一般的に採用されているAPIバージョニングの形式です。
• クエリパラメーターバージョニング：この方式では、APIリクエストのクエリパラメータとしてバージョン番号を指定します。たとえば、https://example-api.com/products?version=v1にリクエストを送信する形になります。
• ヘッダーバージョニング：この方式では、APIリクエストのヘッダーにバージョン番号を指定します。これにより、APIのバージョンをURL構造から切り離すことができます。
• 利用者ベースバージョニング：この方式では、利用者が自身のニーズに応じて適切なバージョンを選択することができます。初回のAPI呼び出し時に使用されたバージョンが、その利用者の情報とともに保存されるため、以降のリクエストはすべてそのバージョンに対して実行されます（ただし、利用者が設定を明示的に変更した場合は除きます）。

これらのバージョニング戦略は、セマンティックバージョニングや日付ベースバージョニングといったバージョニングスキームと併用されるのが一般的である点にも留意が必要です。セマンティックバージョニングでは、たとえば3.2.1のように3つの数字で構成されており、最初の数字は破壊的変更を含む可能性のあるメジャーアップデート、2番目は後方互換性のある新機能の追加、3番目はバグ修正やパッチを意味します。一方、日付ベースバージョニングでは、リリースされた日付そのものをバージョン識別子として使用します。

APIをバージョニングする方法は？

APIバージョニングは、API全体の成功に直結する重要な要素です。これを計画的かつ体系的に実施するには、慎重な準備が求められます。APIの提供者は、できるだけ効果的にバージョニングを行うために、以下のステップに従うことが推奨されます。

ステップ1：バージョニング戦略を選択

APIライフサイクルにおける設計フェーズの段階で、バージョニング戦略をあらかじめ決めておくことが重要です。この戦略は、ポートフォリオ内のすべてのAPIで共通の方針として運用されるべきです。バージョニングを早期に検討することで、破壊的変更の発生を抑えやすく、柔軟性のある設計パターンを選択しやすくなります。また、バージョニング戦略を早い段階で定めておくことで、APIが将来的にどのように進化し、利用者のニーズに応えていくかという現実的なロードマップについて、チーム内で認識を揃えることができます。

ステップ2：新しいバージョンが必要かどうかを確認

変更はAPI開発において避けられないものですが、すべての変更が新しいバージョンを必要とするわけではありません。新バージョンのリリースを検討する前に、チームはその変更の範囲と影響を評価し、後方互換性を保った形で実装できないかを検討すべきです。たとえば、既存の操作を変更するのではなく、新しい操作を追加するという選択肢もあります。破壊的変更を避けられない場合には、利用者体験の向上につながる魅力的な新機能とあわせて導入するタイミングを検討するとよいでしょう。

ステップ3：ドキュメントを更新

APIをバージョニングすることを決めたら、そのリリースに関する情報をAPIドキュメントに反映させることが重要です。たとえば、変更の背景や内容、それが利用者に与える影響、新しいバージョンへのアクセス方法などをわかりやすく伝える必要があります。特に、旧バージョンを将来的に廃止する予定がある場合は、リリーススケジュールや移行手順もあわせて記載しておくとよいでしょう。

ステップ4：新しいバージョンを段階的に展開

可能であれば、チームはまず少数のユーザーグループに対して新しいAPIバージョンを段階的にリリースするとよいでしょう。その後、対象ユーザーからのフィードバックを収集し、より広く公開する前に必要な修正を行います。こうした段階的な展開によって、新しいバージョンが期待通りに動作するかを確認できるだけでなく、実際の利用者がAPIをどのように使用しているかについての貴重な知見も得られます。

ステップ5：古いバージョンを廃止

新しいバージョンが安定したら、チームは移行状況をモニタリングし、どの程度のユーザーが正常に移行できているかを評価する必要があります。移行率が期待通りであれば、古いバージョンを廃止するためのタイムラインを策定し、それを公表するとよいでしょう。この段階では、引き続き古いバージョンを使用しているユーザーに対して、移行に必要な支援を提供することが重要です。

APIバージョニングのベストプラクティスとは？

場当たり的なAPIバージョニングの実施は、APIの利用者にも提供者にも悪影響を及ぼす可能性があります。以下に示すベストプラクティスは、そうしたリスクを回避し、APIバージョニング戦略の成功に役立つものです。

• 拡張性を念頭に置いて設計する：APIの設計段階から、バージョニングの観点を戦略的に取り入れることが重要です。たとえば、ブール値やプリミティブ型の配列といった特定のデータ型は、他の型に比べて破壊的変更の影響を受けやすいため、可能であればAPI設計から除外するのが望ましいでしょう。
• 利用者を理解する：APIに変更を加えるかどうかを判断する際には、利用者がAPIをどのように使っているかを把握することが不可欠です。そのためには、想定外の使われ方も含めた「暗黙的なAPIコントラクト」への配慮が求められます。たとえば、利用者がオブジェクト内のプロパティを名前ではなくインデックスで参照しているケースがあるかもしれません。こうした使い方は提供者の想定外であったとしても、バージョニングの検討時には影響範囲として考慮する必要があります。
• 利用規約にバージョニングポリシーを含める：破壊的変更をどのように定義するのか、変更をどのタイミングで通知するのか、そして新しいバージョンへの移行にどれくらいの猶予期間を設けるのか。これらを利用者に対してあらかじめ明確に示しておくことが重要です。このような取り組みは、特にパートナー向けやパブリックなAPI、また収益化されているAPIにおいて信頼性と透明性を維持するために欠かせません。
• 実装バージョニングとコントラクトバージョニングを分けて考える：バージョニングを検討する際は、APIの実装とコントラクトを切り離して考えることが重要です。たとえば、Node.jsで書かれた実装をRustに書き換えたとしても、コントラクト（たとえばリクエストやレスポンスの構造、エンドポイントの仕様など）が変わらないのであれば、新しいバージョンをリリースすべきではありません。
• 徹底的にテストする：バージョニングはAPIライフサイクルにおける大きな節目であり、円滑に進めるために十分な準備を行うことが重要です。開発およびデプロイの各段階で十分にテストを実施することで、新しいバージョンが期待通りに動作し、利用者に新たな問題を引き起こさないことを確認できます。
• 廃止を計画する：APIの新しいバージョンを開発する際には、古いバージョンをいつ・どのように廃止するかについて、あらかじめ計画しておくことが重要です。これには、廃止ポリシーの策定、利用者への計画の周知、廃止日が近づくにつれて旧バージョンの利用状況をモニタリングすること、そして最終的に関連するサーバーやドキュメントを削除することが含まれます。このように廃止に向けて丁寧な計画と周知を行うことで、予期せぬ混乱のリスクを減らし、不要なインスタンスが長期間残るのを防ぎつつ、利用者が新バージョンへ円滑に移行するための十分な準備期間を確保できます。

PostmanはAPIバージョニングにどのように役立つか？

Postman APIプラットフォームは、Gartner®によって2年連続で「フルライフサイクルAPIマネジメント」分野のビジョナリーに選出されており、チームがAPIに安全かつ計画的に変更を加えるための多くの機能を備えています。Postmanを活用することで、次のようなことが可能になります。

• バージョン管理プラットフォームとの組み込み統合を活用する：Postmanは、GitHub、Bitbucket、GitLab、Azure DevOps といったリモートリポジトリと連携でき、APIをそれらのリポジトリに接続することが可能です。接続後は、Postman上からGitベースのバージョン管理を使ってブランチの切り替えや変更のプル・プッシュを簡単に実行できます。
• Postmanアーティファクトで安全にコラボレーションする：Postmanには、コレクション、環境、Postman Flowsなどの成果物に対して使えるバージョン管理機能が組み込まれています。たとえば、チームメンバーは編集権限がなくても、これらのエンティティをフォークしてプルリクエストを作成できるため、安全に反復的な開発作業を進めながら、効果的に共同作業を行うことができます。
• 公開ドキュメントを簡単に作成する：Postmanでは、各リクエストやエンドポイントの詳細情報や、さまざまなクライアント言語でのコードサンプルを含む公開ドキュメントを簡単に生成・公開できます。このドキュメントはコレクションの内容に応じて自動的に更新されるため、常に内容を最新の状態に保つことができます。
• 手動および自動テスト機能を活用する：Postmanには、新しいAPIバージョンの動作を検証するための充実したテスト機能が備わっています。たとえば、コレクションランナーを使ってリクエストを連結し、テスト結果を記録できます。また、 NewmanやPostman CLIを使用すれば、CI/CDパイプライン内で新バージョンのAPIに対して自動テストを実行することも可能です。