API アセットのバージョンの変更
Anypoint Exchange では、次の API アセットを作成できます。
-
REST API (RAML または OAS)
-
HTTP API
-
SOAP API
このドキュメントでは、これらのアセットのバージョンを変更する方法について説明します。
各 API アセットには、アセットバージョン [Version (バージョン)] 項目と、API 仕様バージョンの [API version (API バージョン)] 項目があります。RAML、OAS、および SOAP アセットの場合、API 仕様バージョンはその仕様内にコード化されています。
Exchange のアセットバージョンは、メジャー、マイナー、およびパッチリリースの セマンティックバージョン設定モデルに従いますが、ビルドメタデータはサポートされません。たとえば、アセットのバージョンが 2.4.6 でメジャーバージョンが 2.x.x である場合、そのマイナーバージョンは 2.4.x で、パッチバージョンは 2.4.6 になります。
HTTP API アセットはポリシーまたはプロキシのみを提供できるエンドポイントです。HTTP API には、メジャーバージョンの増加のみがあり、マイナーバージョンやパッチバージョンの変更はありません。
アセットの新しいバージョンを作成する場合、以前のバージョンの名前、アイコン、説明が使用されます。これらのプロパティを変更するには、「アセットの説明」の手順を使用します。名前、アイコン、説明に対する変更は、アセットのすべてのバージョンに適用されます。
| 新しいアセットバージョンは、組織のアセット制限に含まれます。 |
新しい API アセットのデプロイ
[Publish new asset (新規アセットをパブリッシュ)] ボタンを使用して、API アセットを Exchange に直接デプロイできます。[Publish a new asset (新規アセットをパブリッシュ)] ウィンドウの [Advanced (詳細)] セクションでは、[Version (バージョン)] 項目でアセットのバージョン、[API version (API バージョン)] 項目で API 仕様のバージョンを指定できます。
更新された API 仕様に新しいバージョンと古いバージョンの後方互換性がない変更がある場合にのみ、API バージョンを変更してください。
RAML または OAS バージョンの変更
Exchange 内の RAML および OAS API 仕様では、[Add version (バージョンを追加)] ボタンを使用して Exchange 内からバージョン番号を変更します。
-
アセットの詳細ペインから、[Add version (バージョンを追加)] をクリックします。
-
(必須) [API specification (API 仕様)] に [Method (メソッド)] を選択します。
-
(必須) [File upload (ファイルのアップロード)] から [Choose file (ファイルを選択)] をクリックします。OAS の場合、.yaml または .json ファイルの種類の OAS ファイルを選択します。RAML の場合、.raml ファイルの種類の RAML ファイルを選択します。zip ファイルのルートディレクトリにあるアップロード用のファイルを含む zip ファイルも使用できます。
-
アップロードされるファイルが zip の場合、[Main file (メインファイル)] を指定します。そうしないと、アップロードするファイルと同じ名前のファイルが使用されます。
-
(必須) [Version (バージョン)] で、アセットの新しいバージョンを入力します。
-
(必須) [API version (API バージョン)] で、API 仕様のバージョンを入力します。 [Version (バージョン)] と [API version (API バージョン)] の値は一致している必要があります。特定の API バージョンではマイナーバージョンの更新のみを選択できます。[Version (バージョン)] でメジャー番号を設定する場合、[API version (API バージョン)] も増やします。マイナーまたはパッチバージョンの更新を選択した場合、API バージョンは変更されません。
-
(省略可能) [Lifecycle state (ライフサイクル状態)] を選択します。デフォルトは [Stable (安定)] です。
-
[Publish (パブリッシュ)] をクリックします。
[Manage versions (バージョンを管理)] ボタンを使用してバージョンを変更することもできます。詳細は、「バージョンの管理」を参照してください。
次のセクションで説明するように、RAML のバージョン番号を変更します。
仕様から RAML バージョンを変更する
RAML 仕様の version: 要素を変更します。
Anypoint Platform の Design Center 機能で、テキストエディターまたは API Designer を使用できます。
RAML 仕様の version 要素を更新して Exchange にパブリッシュすると、パブリッシュメニューには自動的に version: 要素からの変更が反映されます。
Exchange にパブリッシュするときに RAML バージョンを変更する
-
Design Center から、API を開きます。変更は必要ありません。
-
[Publish to Exchange (Exchange へのパブリッシュ)] をクリックします。
-
[API Version (API バージョン)] の値を変更します。[Asset Version (アセットバージョン)] (Exchange アセットのバージョン) を変更することもできます。
RAML ファイルに基づく REST API が Design Center から作成されて Exchange にパブリッシュされると、API バージョンが RAML ファイルの version プロパティから取得されます。
既存の REST API の新しい API バージョンをパブリッシュすると、アセットのバージョンのメジャーセクションが更新されます。
複数の API とアセットのバージョン
各 Exchange アセットは複数のアセットバージョンを持つことができます。REST、SOAP、および HTTP API には API バージョンも含まれます。
各 API バージョンで、複数のアセットバージョンをパブリッシュできます。これらのアセットバージョンは、同じメジャーバージョンである必要があります。
たとえば、同じ API の複数のバージョンをパブリッシュすると、 バージョンは次のようになります。
| API バージョン | アセットバージョン |
|---|---|
v1 |
1.0.0 |
v1 |
1.0.1 |
v1 |
1.1.1 |
v2 |
2.0.0 |
v2 |
2.0.2 |
v3 |
3.1.0 |
ただし、これらの例の値は Exchange では許可されていません。
| API バージョン | アセットバージョン |
|---|---|
v1 |
1.0.0 |
v2 |
1.0.1 |
API バージョン設定のベストプラクティス
API は長期間使用するために設計する必要がありますが、変更は避けられないため、API が完全に安定することはありません。
重要なのは、包括的なバージョン設定戦略を使用して変更を管理することです。これには、複数月の廃止スケジュールと、変更について十分に詳しく説明された最新のドキュメントが含まれます。
すべての変更で新しいバージョンが必要なわけではありません。後方互換性のために設計された API は通常、大幅な変更は必要とせず、軽微な変更やパッチの変更を使用します。
API をそのように設計することが不可能な場合もあります。次の表に、新しいバージョンを導入するタイミングと新しいバージョンが不要な場合の概要を示します。通常、ユーザーが [Add new API operation (新しい API 操作を追加)] をクリックしたときに、マイナーバージョンが増えます。
| 変更の種別 | 新しいメジャーバージョンを必要とする変更 | 新しいメジャーバージョンを必要としない変更 |
|---|---|---|
サービス契約 |
|
新しい API 操作の追加 |
データ契約 |
|
|
表現の形式 |
既存の表現の削除 |
新しい表現の追加 |
アクセシビリティ |
権限の制限 |
権限の緩和 |
新しいメジャーバージョンを導入するタイミング
次の場合に新しいメジャーバージョンを導入する必要があります。
-
サービス品質 (QoS)
変更によって応答時間や可用性などのサービス品質に影響が出る場合は、API のアプリケーションで後方互換性が失われることがあるため、API のメジャーバージョンと API の変更が必要になる可能性があります。
-
出力メッセージドメイン値の変更
API を使用するアプリケーションは、応答メッセージ内の項目値のドメインに依存します。たとえば、API は特定の商品や特定の支払方法のみを返す場合があります。API がドメイン外の値を返し始めた場合、既存のコンシューマーに悪影響を及ぼす可能性があります。この場合、新しいメジャーバージョンと新しい API バージョンの導入を検討します。
バージョン番号を変更するタイミング
-
メジャーバージョン
API ユーザーにコンシューマー側のインターフェースの採用を要求する API の構造を変更するとき (操作に新しい必須の引数を追加する場合など)。
-
マイナーバージョン
新しい省略可能な要素の提供など、既存の API ユーザーには何も変更を求めない、後方互換性のための変更を API に導入するとき。
-
パッチバージョン
後方互換性のためのバグ修正や、ドキュメントの更新を導入するとき。
詳細は、 「セマンティックバージョン設定」を参照してください。