API アセットのバージョンの変更

Anypoint Exchange では、次の API アセットを作成できます。

  • REST API (RAML または OAS)

  • HTTP API

  • SOAP API

このドキュメントでは、これらのアセットのバージョンを変更する方法について説明します。Exchange のバージョンは、メジャー、マイナー、およびパッチリリースの ​​セマンティックバージョンン設定​に従います。

各 API アセットには、アセットのバージョン番号を示す ​[Version (バージョン)]​ 項目と、API 仕様のバージョンを示す ​[API version (API バージョン)]​ 項目があります。RAML、OAS、および SOAP アセットの場合、API 仕様バージョンはその仕様内にコード化されています。HTTP API アセットはポリシーまたはプロキシを提供できるエンドポイントにすぎないため、[API version (APIバージョン)] 項目は適用されません。

[Version (バージョン)] および [API Version (API バージョン)] 項目は、新しいアセット を追加したとき、または既存のアセットに新しいバージョンを追加したときにのみ表示されます。

HTTP API の場合、アセットはエンドポイントにすぎないため、新しい公開ごとにパッチまたはマイナーバージョンを増やすことは無意味です。そのため、HTTP API にはメジャーバージョンの増加と 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

これにより、(​<<「新しい API バージョンのデプロイ」>>​で示されている) ​[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) — 応答時間や可用性などのサービス品質が変更の影響を受ける場合、QoS によって API を使用するアプリケーションが中断される可能性があるため、API バージョンの変更が必要な場合があります。

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

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

  • メジャーバージョン: API ユーザにコンシューマ側のインターフェースの採用を要求する API の構造を変更するとき。

  • マイナーバージョン: API ユーザが変更を必要としない API への変更を導入するとき、またはバグを修正するとき。マイナーバージョンの増加は、ユーザがまだ同じ API バージョンを使用可能で、そのバージョンと前のバージョンの互換性がない場合に行います。詳細は、 ​​「セマンティックバージョン設定」​を参照してください。

  • パッチバージョン: 後方互換性のある変更を導入するとき。

アプリケーション 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 バージョンごとに異なるドキュメントページを作成できます。

編集中の API バージョンは、API 名の横にあるボタンから変更できます。

ex title version setting

Was this article helpful?

💙 Thanks for your feedback!