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 アセットのデプロイ

[New asset (新規アセット)]​ ボタンを使用して、API アセットを Exchange に直接デプロイできます。[Publish a new asset (新規アセットをパブリッシュ)]​ ウィンドウの [Advanced (詳細)] セクションでは、[Version (バージョン)]​ 項目でアセットのバージョン、[API version (API バージョン)]​ 項目で API 仕様のバージョンを指定できます。

ex publish a new asset

更新された API 仕様に新しいバージョンと古いバージョンの後方互換性がない変更がある場合にのみ、API バージョンを変更してください。

RAML または OAS バージョンの変更

Exchange 内の RAML および OAS API 仕様では、Exchange ユーザインターフェースで [Add new version (新規バージョンを追加)]​ ボタンを使用して Exchange 内からバージョン番号を変更できます。

ex add new version

これにより、([deploy-a-new-api-asset]​で示されている) [Publish a new asset (新規アセットをパブリッシュ)]​ ウィンドウが開きます。

[File upload (ファイルのアップロード)]​、[Main file (メインファイル)]​、および [Version (バージョン)]​ 項目は必須です。

項目 説明

File upload (ファイルのアップロード)

OAS の場合、.yaml または .json ファイルの種類の OAS ファイルを選択します。 RAML の場合、.raml ファイルの種類の RAML ファイルを選択します。zip ファイルのルートディレクトリにある アップロード用のファイルを含む zip ファイルも使用できます。

Main file (メインファイル)

アップロードされるファイルが zip の場合、メインファイルを指定します。そうしないと、アップロードするファイルと同じ名前のファイルが使用されます。

Version (バージョン)

新しいバージョン番号。[Version (バージョン)] と [API version (API バージョン)] の値は、 特定の API バージョンではマイナーバージョンの更新のみを選択可能という条件を両方が満たす必要があります。[Version (バージョン)] で メジャー番号を設定する場合、[API version (API バージョン)] も増やします。マイナーまたはパッチバージョンの更新を選択した場合、[API version (API バージョン)] は変更しません。

次のセクションで説明するように、RAML のバージョン番号を変更することもできます。

仕様から RAML バージョンを変更する

RAML 仕様の version:​ 要素を変更します。 Anypoint Platform の Design Center 機能で、テキストエディタまたは API Designer を使用できます。 RAML 仕様の version 要素を更新して Exchange にパブリッシュすると、パブリッシュメニューには自動的に version:​ 要素からの変更が反映されます。

Exchange にパブリッシュするときに RAML バージョンを変更する

  1. Design Center から、API を開きます。変更は必要ありません。

  2. [Publish to Exchange (Exchange にパブリッシュ)] ボタンをクリックします。

    apim publish api spec
  3. [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 エンドポイントの削除

  • API 操作の効果の変更

  • API 操作の応答種別の変更

  • 新しい必須操作引数の追加

新しい API 操作の追加

データ契約

  • 既存の要素 (または属性) の削除

  • 新しい必須要素 (または必須属性) の追加

  • 既存の要素 (または属性) の変更

  • 省略可能な要素 (または属性) の追加

  • 派生した要素種別の追加

表現の形式

既存の表現の削除

新しい表現の追加

アクセシビリティ

権限の制限

権限の緩和

新しいメジャーバージョンを導入するタイミング

次の場合に新しいメジャーバージョンを導入する必要があります。

  • サービス品質 (QoS)

    変更によって応答時間や可用性などのサービス品質に影響が出る場合は、API のアプリケーションで後方互換性が失われることがあるため、API のメジャーバージョンと API の変更が必要になる可能性があります。

  • 出力メッセージドメイン値の変更

    API を使用するアプリケーションは、応答メッセージ内の項目値のドメインに依存します。たとえば、API は特定の商品や特定の支払方法のみを返す場合があります。API がドメイン外の値を返し始めた場合、既存のコンシューマに悪影響を及ぼす可能性があります。この場合、新しいメジャーバージョンと新しい API バージョンの導入を検討します。

バージョン番号を変更するタイミング

  • メジャーバージョン

    API ユーザにコンシューマ側のインターフェースの採用を要求する API の構造を変更するとき (操作に新しい必須の引数を追加する場合など)。

  • マイナーバージョン

    新しい省略可能な要素の提供など、既存の API ユーザには何も変更を求めない、後方互換性のための変更を API に導入するとき。

  • パッチバージョン

    後方互換性のためのバグ修正や、ドキュメントの更新を導入するとき。

詳細は、https://semver.org/[「セマンティックバージョン設定」]​を参照してください。

アプリケーション URL 内の API バージョン

API バージョンをアプリケーション URL に含めて、コンシューマがコールするバージョンを選択できるようにします。

  • オンプレミスデプロイメントの場合、バージョンはベース URI 内にあり、URL に表示されます。

    http://www.example.org/v1/api/customer/1234

命名規則

API バージョンの定義には次のルールを使用できます。

  • 「v」プレフィックスを付けてバージョンを指定する。

  • 単純な序数 (「v1」、「v2」など) を使用する。

  • 「v1.2」などのドット表記は避ける。

  • URL の一部としてメジャーバージョンのみを指定する。

API バージョンのドキュメント化

Exchange には、API コンシューマのアセットに関する情報を含むドキュメントページがあります。 マイナーアセットバージョンごとに異なるドキュメントページを作成できます。

API 名の横にあるメニューで、編集するマイナーアセットバージョンを選択してください。

マイナーバージョン選択メニュー

Was this article helpful?

💙 Thanks for your feedback!