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利用者ベースのバージョニング：API利用者がニーズに応じて利用するバージョンを選択できる方法です。この手法では、API利用者が初めてAPIを呼び出した時点のバージョンが利用者情報とともに保存されます。その後のAPIコールは、利用者が設定を明示的に変更しない限り、同じバージョンに対して実行されます。

これらのバージョニング手法は、セマンティックバージョニングや日付ベースのバージョニングといったバージョニング方式と組み合わせて使用されます。セマンティックバージョニングでは、3.2.1 のような3つの数字でバージョンを表します。1つ目の数字は破壊的変更を伴う可能性があるメジャーアップデート、2つ目の数字は後方互換性を維持した新機能の追加、3つ目の数字はバグ修正やパッチを表します。一方、日付ベースのバージョニングでは、リリース日をもとにバージョンを識別します。

APIをどのようにバージョニングしますか？

APIバージョニングは、API全体の成功を左右する重要な取り組みです。そのため、計画的かつ段階的に進められるよう、十分な準備が欠かせません。API提供者は、APIを効果的にバージョニングするために、次の手順に従うことをおすすめします。

ステップ1：バージョニング戦略を決める

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

ステップ2：新しいバージョンが本当に必要か確認する

API開発では変更は避けられませんが、すべての変更で新しいバージョンが必要になるわけではありません。新しいバージョンをリリースする前に、チームは変更の範囲と影響を評価し、後方互換性を維持したまま実現できる方法がないかを検討することが重要です。たとえば、既存の操作を変更する代わりに、新しい操作を追加する方法を選べる場合があります。破壊的変更を避けられない場合は、API利用者の体験向上につながる大きな新機能のリリースに合わせて導入することも検討するとよいでしょう。

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

APIをバージョニングすることを決めたら、リリース情報を反映するようにAPIドキュメントを更新することが重要です。たとえば、変更の目的やAPI利用者への影響、新しいバージョンへのアクセス方法などを明記するとよいでしょう。また、特に将来的に旧バージョンを非推奨（deprecated）にする予定がある場合は、リリーススケジュールや移行手順もあわせて記載することをおすすめします。

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

可能であれば、新しいAPIバージョンは少数のユーザーを対象に段階的にリリースすることをおすすめします。その後、ユーザーからのフィードバックを収集し、問題があれば対応したうえで、より広い範囲へ展開します。この方法により、新しいバージョンが期待どおりに動作することを確認できるだけでなく、実際のAPI利用者がAPIをどのように利用しているかについての貴重な知見も得られます。

ステップ5：旧バージョンを非推奨にする

新しいバージョンが安定したら、どれだけのAPI利用者が新しいバージョンへ移行したかを把握するために、利用状況を継続的に確認します。想定どおりに移行が進んでいることを確認できたら、旧バージョンを非推奨（deprecated）にするスケジュールを策定し、利用者へ周知します。この段階では、引き続き旧バージョンを利用しているAPI利用者へのサポートも重要です。新しいバージョンへの移行を支援することで、スムーズな移行を促進できます。

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

場当たり的なAPIバージョニングは、API提供者とAPI利用者の双方に悪影響を及ぼす可能性があります。次のベストプラクティスを取り入れることで、よくある落とし穴を避け、APIバージョニング戦略を成功へ導くことができます。

• 拡張性を考慮して設計する：API設計の段階から、バージョニングを見据えた設計を行うことが重要です。たとえば、ブール値やプリミティブ型の配列など一部のデータの型は、ほかの型に比べて破壊的変更の影響を受けやすいため、可能であればAPI設計での利用を避けることをおすすめします。
• API利用者を理解する：APIを変更するかどうかを判断する際は、API利用者がどのようにAPIを利用しているかを把握することが重要です。その際には、「見えないAPIコントラクト（Invisible API Contract）」も考慮する必要があります。これは、API提供者が想定していなかったAPIの利用方法を指します。たとえば、API利用者がプロパティ名ではなくオブジェクト内のインデックスを使ってプロパティにアクセスしている場合があります。このような利用方法も、バージョニングの際には考慮に入れる必要があります。
• 利用規約にバージョニングポリシーを明記する：どのような変更を破壊的変更と定義するのか、変更をいつ事前通知するのか、新しいバージョンへ移行するまでにどれくらいの期間を設けるのかをAPI利用者へ明確に伝えることが重要です。これは、パートナー向けAPIやパブリックAPI、とりわけ収益化されているAPIでは特に重要です。
• 実装のバージョニングと契約のバージョニングを分離する：バージョニングでは、APIの実装とAPIコントラクトを切り分けて考えることが重要です。たとえば、Node.jsで実装したAPIをRustで書き直しても、APIコントラクトに変更がなければ、新しいAPIバージョンをリリースする必要はありません。
• 十分にテストする：バージョニングはAPIライフサイクルにおける重要なイベントです。そのため、スムーズに進められるよう、徹底したテストを実施することが重要です。開発時とデプロイ時の十分なテストにより、新しいバージョンが期待どおりに動作し、API利用者に新たな問題を引き起こさないことを確認できます。
• 非推奨化を計画する：新しいAPIバージョンを開発する際は、旧バージョンをいつ、どのように非推奨（deprecated）にするかもあらかじめ計画しておくことが重要です。具体的には、非推奨ポリシーの策定、API利用者への周知、非推奨日が近づくにつれて旧バージョンの利用状況を監視し、最終的にサーバーやドキュメントを廃止するといった対応が含まれます。綿密な計画と十分なコミュニケーションにより、混乱を防ぎ、旧バージョンが必要以上に使われ続けることを避けるとともに、API利用者が新しいバージョンへ移行するための十分な時間を確保できます。

PostmanはAPIバージョニングをどのように支援しますか？

Postman APIプラットフォームは、Gartner®の「Full Lifecycle API Management」部門で2年連続「Visionary」に選出されており、チームがAPIを安全に変更できるさまざまな機能を備えています。Postmanでできることは次のとおりです。

• バージョン管理プラットフォームとの組み込み連携を活用する：Postmanでは、GitHub、Bitbucket、GitLab、Azure DevOps上のリモートリポジトリに接続できます。APIをリポジトリに接続すると、Postmanを離れることなく、Gitベースのバージョン管理を利用してブランチの切り替えや変更のプル・プッシュを行えます。
• Postmanアーティファクトで安全に共同作業する：Postmanには、Postmanコレクション、環境、Postman Flowsで利用できる組み込みのバージョン管理機能が用意されています。たとえば、チームメンバーは編集者ロールがなくてもこれらをフォークしてプルリクエストを作成できるため、安全なイテレーションと効率的なコラボレーションを実現できます。
• パブリックドキュメントを簡単に作成する：Postmanなら、パブリックドキュメントを簡単に公開できます。公開されたドキュメントには、各リクエストやエンドポイントの詳細に加え、さまざまなクライアント言語のコードサンプルも自動的に含まれます。また、ドキュメントは自動更新されるため、コレクションとの同期が失われる心配もありません。
• 手動テストと自動テストを活用する：Postmanには、新しいAPIバージョンの機能を検証できる充実したAPIテスト機能が用意されています。たとえば、Postmanのコレクションランナーを使って複数のリクエストを連続実行し、テスト結果を記録できます。また、NewmanやPostman CLIを利用すれば、CI/CDパイプライン内で新しいAPIバージョンに対するテストを実行できます。