テナント管理APIの概要

StorageGRID Webscaleには、テナント アカウントを管理するためのREST APIが用意されています。

テナント管理APIのドキュメント

テナント管理APIは、オープン ソースのAPIプラットフォームであるSwaggerを使用してAPIのドキュメントを提供しています。Swaggerでは、ユーザ インターフェイスを使用してパラメータやオプションを変更した場合のAPIの動作を確認しながら、APIの開発を進めることができます。Swaggerのドキュメントは、標準的なWebテクノロジとJavaScript Object Notation(JSON)データ形式について十分理解していることを前提としています。

注意:Swaggerユーザ インターフェイスを使用して実行するAPI処理はすべてライブ処理です。設定やその他のデータを誤って作成、更新、または削除しないように注意してください。

テナント管理APIのドキュメントにアクセスするには、テナント管理インターフェイスにサインインし、Webアプリケーション ヘッダーで[Help] > [API Docs]を選択します。
[API Docs]メニュー項目にアクセスする方法を示すスクリーンショット

API

各REST APIコマンドは、APIのURL、HTTPアクション、必須またはオプションのURLパラメータ、および想定されるAPI応答で構成されます。

Swaggerのユーザ インターフェイスでは、次の例のように、各API処理に関する詳細情報とドキュメントを参照できます。ローカル テナント ユーザに関する情報を表示するには、shortNameパラメータの値としてそのユーザの一意の名前を入力し、[Try it out]をクリックします。


SwaggerドキュメントUIのスクリーンショット

テナント管理APIには次のセクションが含まれています。

テナント管理APIのバージョン管理

テナント管理APIは、バージョン管理を使用して無停止アップグレードをサポートします。たとえば、次の要求URLではバージョン2のAPIが指定されています。

https://hostname_or_ip_address/api/v2/authorize

テナント管理APIで後方互換性のない変更が行われた場合は、APIのメジャー バージョンが上がります。たとえば、APIに対して互換性のない変更が行われると、バージョンが1.1から2.0に上がります。テナント管理APIで後方互換性のある変更が行われた場合は、マイナー バージョンが上がります。後方互換性のある変更には、新しいエンドポイントやプロパティの追加などがあります。たとえば、APIに対して互換性のある変更が行われると、バージョンが1.0から1.1に上がります。

StorageGRID Webscaleソフトウェアを初めてインストールした時点では、テナント管理APIの最新のバージョンのみが有効になっています。ただし、StorageGRID Webscaleを新しいメジャー バージョンにアップグレードした場合、少なくともメジャー リリース1つ分のアップグレードにおいては、古いAPIバージョンにも引き続きアクセスできます。

古い要求は、次の方法で廃止とマークされます。
  • 応答ヘッダーが「Deprecated: true」となる。
  • JSON応答の本文に「deprecated: true」が追加される。

現在のリリースでサポートされているAPIバージョンの特定

サポートされているAPIのメジャー バージョンのリストを返すには、次のAPI要求を使用します。
GET https://{{IP-Address}}/api/versions
{
    "responseTime": "2016-10-03T14:49:16.587Z",
    "status": "success",
    "apiVersion": "2.0",
    "data": [
        1,
        2
    ]
}

要求のAPIバージョンの指定

APIのバージョンは、パス パラメータ(/api/v2)またはヘッダー(Api-Version: 2)を使用して指定できます。両方を指定した場合、ヘッダーの値がパスの値を上書きします。

curl https://[IP-Address]/api/v2/org/config

curl -H "Api-Version: 2" https://[IP-Address]/api/org/config