APIバージョニングとは？ - 基準と戦略

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

APIに対して、操作面や構造面の変更を行い、利用者の増大や変化する要求に応えられるようにする手順です。

時間が経つにつれて、初期のAPIの構造や機能は古くなりやすくなります。最新の状態を維持するため、バグの修正、機能の強化、新たな機能の追加が求められます。

API構造の変更は手間がかかりますが、現代の利用者の要求に応えるためには不可欠な作業です。

APIのバージョニングを行う際に留意すべき主な点は以下の通りです。

• 利用者側の不整合を修正する
• コード変更による破壊的な影響が利用者に及ばないか確認する
• 求められた変更を取り込むための十分な時間を利用者に与える

‍

APIのバージョンを作成するタイミング

基本的には、既存のAPIが時代遅れと感じられる際にバージョン更新を行いますが、特定の状況では確実にバージョニングが必要となります。

バージョン更新が必要な場合は以下の通りです。

• APIリリース後に、大小を問わずフィールドやルーティングの変更が行われた場合
• APIのペイロード構造がいずれかのレベルで変更された場合
• 設計上の欠陥修正や不正なHTTP実装の解消のために、APIエンドポイントが削除された場合

以上のような変更が行われた場合、初期のAPIを利用して開発された製品に大きな支障が出ないよう、バージョニングが必要です。

さらに、新たなAPIエンドポイントやレスポンスパラメータを追加する際にもバージョニングが求められます。ただし、これらの場合は大規模な更新ではなく、軽微な変更で十分です。

なぜバージョニングを行うべきか？

一見、地味なREST APIのバージョニングに興味を持たないかもしれませんが、バージョン付きAPIの利用は二つの点で重要です。

1. ‍破壊的な変更

コードや元のAPI構造の調整は、利用者側に直接的な影響を及ぼす可能性があります。この方法を採用しなければ、利用者が自らのアプリに対して変更を強いられることもあり得ます。

以下は、破壊的な変更に該当する例です。

• 元のリクエスト/レスポンスフォーマットの種類を変更する
• プロパティのデータ型または名称を一新する
• 例えば「必須」ヘッダーのような、新たな重要項目を追加する
• 説明など、既定のレスポンス項目を削除する

これらの変更は、元のAPIを用いて開発されたアプリに直接影響を与えます。新しいAPIバージョンが導入されなければ、すべてのアプリが大きな不具合に見舞われる恐れがあります。そのため、API開発者はバージョニング戦略を採用すべきです。また、破壊的な変更が放置されるとセキュリティの脆弱化にも繋がります。

2. ‍APIにおける変更管理

APIの利用者が直接変更を加えることは避けるべきです。大規模な変更や目立つ変更は、バージョニングによってのみ対処されるべきです。変更管理によって、これが確実に実現されます。

このプロセスは、予想される重大なAPI変更を回避するために有効で、以下の原則に基づいて行われます。

• 現行のAPI項目やエンドポイントへの継続的なサポートを提供する
• 既存のものを変更するのではなく、新たなエンドポイントや項目を提供する
• 旧式のエンドポイントや項目は慎重に終了させる

これらの原則に従うことで、バージョニングの手間を軽減し、導入が容易になります。

API契約

APIバージョニングのベストプラクティスの中でも、API契約の作成と更新は最も重要なポイントです。API契約とは、API開発者と利用者間の法的かつ詳細な合意書を指します。この文書（電子または紙媒体）には、APIの機能、提供されるサービス、利用時の利用者の責任などが明記されます。

すなわち、APIの提供者と利用者間での透明性を促す手段です。また、APIの変更を記録し、その影響について利用者に通知する役割も担います。契約書の内容は、主要なAPIタイプ、REST APIを含むすべてのAPIメディアタイプをカバーしますが、URIに関しては記載されていません。

‍

APIバージョニングの種類

APIの利用方法は一様ではないため、バージョニングにもいくつかの種類があります。代表的な手法をご紹介します。

• ‍クエリパラメータによるバージョニング

名称が示す通り、クエリ変数を用いてAPIのバージョンを指定する方法です。効果的で実装も容易です。この手法により、新たなバージョンが設定されるまで既定のAPIバージョンを維持することが可能です。

• ‍URIによるバージョニング

URI内にAPIのバージョン情報を記載する方法です。実装が容易で効果も高く、URIパスに「v」プレフィックスを付ける必要があります。シンプルではありますが、各APIエンドポイントを個別に設定するため、結果的にURIが冗長になるという欠点もあります。

この手法は、現在のアプリのバージョン告知に利用されるものの、エンドポイント自体のバージョン管理は行いません。

• ‍カスタムヘッダーによるバージョニング

ヘッダー内にAPIのバージョン情報を記載する方法です。迅速な更新が可能で、バージョン番号を利用するだけのため、URIに余計な記述を加える必要がなく、端的なバージョニングが実現します。

結論

この記事で多くの点を学びました。簡単に振り返ると、

• APIバージョニングとは、APIのバージョンを明示的に変更することを指します。
• 様々な種類や手法が存在します。
• 破壊的または重大な変更が行われた場合、バージョニングは必須です。
• APIの変更管理は、従来のものを完全に変えるのではなく、新機能の追加に重点を置きます。

これらの知識はAPIバージョニングの基本ですが、利用者の要求により多少の変更が加えられることもあります。APIの進化は複雑な作業であり、完全な実現が求められます。その際、APIの守りから目を離さず、安全な運用を心掛けることが重要です。