REST

SoftLayer は、RPC スタイルの API サービスに加えて、RESTful API も提供します。ご使用のプログラミング言語が SOAP または XML-RPC を十分にサポートせず、単純な HTTP プロトコル・アクションを実行し、XML または JSON データを解釈できる場合は、REST API を使用してください。

REST URL

REST API URL は、SoftLayer のオブジェクト階層を簡単にトラバースするよう構築されています。基本的な REST 要求は以下の構造になります。

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • すべての REST 要求は、プライベート・ネットワーク要求でさえ、HTTP SSL を使用して渡されなければなりません。
  • HTTP 認証による要求の認証には、API ユーザー名とキーを使用します。
  • REST 要求の基本のホスト名とフォルダー名は、api.softlayer.com/rest/v3/api.service.softlayer.com/rest/v3/ のどちらかです。SoftLayer のプライベート・ネットワークを介して REST API にアクセスするには、api.service.softlayer.com/rest/v3/ を使用します。この方が、SoftLayer との通信には安全性が高い方法ですが、API 呼び出しを行うシステムが SoftLayer のプライベート・ネットワーク上にある必要があります (SoftLayer から購入するか、SoftLayer のプライベート・ネットワーク VPN にログインするかのどちらかです)。
  • 呼び出したい API サービスの名前 (例: 「SoftLayer_Account」または「SoftLayer_Hardware_Server」) を使用してベース URL をフォローアップします。
  • API 要求に初期化パラメーターが必要である場合は、スラッシュの後に初期化パラメーター ID を付けたものを URL に追加します。
  • SoftLayer REST API は、XML か JSON のどちらかの定様式出力を戻すことができます。「.xml」または「.json」を要求の末尾に追加し、受け取るデータの形式を指定します。

次のような要求は、呼び出そうとしている API サービスの getObject() メソッドを呼び出します。SoftLayer_Account::getObject には初期化パラメーターが必要ないので、その REST URL は次のようになります。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account.json

ただし、特定の SoftLayer_Hardware_Server レコードの getObject() メソッドを呼び出すには、次の URL を使用してください。ここでは、「1234」が、取得したいサーバーの ID であることを前提としています。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234.json

初期化パラメーターの後にメソッドの名前を指定することによって、getObject() 以外の API メソッドを呼び出します。メソッドが「get」で始まる場合は、メソッド名からワード「get」を削除し、その先頭文字を大文字に変換してください。このメソッドは、オブジェクトのリレーショナル・プロパティーに素早くアクセスするのにも使用できます。例えば、SoftLayer_Account API サービスの getHardware() メソッドと hardware リレーショナル・プロパティーには、次の URL でアクセスできます。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json

同様に、サーバーのネットワーク・コンポーネントには、次の URL でアクセスできます。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents.json

特定のオブジェクト・コンポーネントをドリルダウンするには、初期化パラメーター ID とリレーショナル・プロパティーの組み合わせをチェーニングします。追加される各 ID は、その特定のリレーショナル・プロパティーをドリルダウンします。例えば、サーバー 1234 のネットワーク・コンポーネント (ID 5678 を持つ) に到達したい場合は、次の URL を使用します。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents/5678.json

そのネットワーク・コンポーネントのアップリンク接続に到達するには、次の URL を使用します。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents/5678/uplinkNetworkComponents.json

HTTP 要求タイプ

DELETE

サービスの deleteObject() メソッドの代わりに、オブジェクトの削除に HTTP DELETE 要求を使用します。例えば、SoftLayer の DNS サーバーからドメイン・レコード 1234 を削除するには、HTTP DELETE 要求を以下の URL に渡します。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234.json

GET

単純なオブジェクト検索やメソッド呼び出しには、HTTP GET 要求を使用します。例えば、次の URL に対する HTTP GET 要求でドメイン・レコード ID 1234 を取得します。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234.json

POST

サービスの createObject() メソッドまたは createObjects() メソッドの代わりに、オブジェクトの作成に HTTP POST 要求を使用します。オブジェクトのスケルトン構造を含む「パラメーター」と呼ばれる単一エレメント、および API サービスの createObject() メソッドで必要なその他のパラメーターを含む、単一の JSON または XML 構造を POST します。例えば、SoftLayer の DNS サーバーでドメイン・レコードを作成するには、以下のデータと一緒に HTTP POST 要求を以下の URL に渡します。

{
    "parameters" : [
        {
            "name" : "example.org",
            "resourceRecords" : [
                {
                    "type" : "a",
                    "host" : "@",
                    "data" : "127.0.0.1"
                }
            ]
        }
    ]
}
https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain.json

PUT

サービスの editObject() メソッドまたは editObjects() メソッドの代わりに、オブジェクトの編集に HTTP PUT 要求を使用します。オブジェクトのスケルトン構造を含む「パラメーター」と呼ばれる単一エレメント、および API サービスの editObject() メソッドで必要なその他のパラメーターを含む、単一の JSON または XML 構造を PUT します。例えば、SoftLayer の DNS サーバーでドメイン・レコード 1234 内のドメイン・リソース・レコード 5678 を編集して、data を "10.0.0.1" に変更するには、以下のデータと一緒に HTTP PUT 要求を以下の URL に渡します。

{
    "parameters" : [
        {
            "data" : "10.0.0.1",
        }
    ]
}
https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234/ResourceRecords/5678.json

メソッド・パラメーターの受け渡し

各パラメーターを URL のパスに付加することによって、パラメーターは REST API に渡されます。
メソッドごとに資料にリストされているのと同じ順に、上から下に渡されなければなりません。

例えば、SoftLayer_Monitoring_Agent::setActiveAlarmSubscriber には、userRecordId パラメーターが必要です。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Monitoring_Agent/1234/setActiveAlarmSubscriber/5678.json

メソッドの中には、SoftLayer_Dns_Domain_ResourceRecord::createObjects などのアレイである単一パラメーターを要求するものがあります。

 {
  "parameters":
    [
      [
        {"host":"hosta","data":"127.0.0.1","ttl":"900","type":"a","domainId":"1234"}
        ,
        {"host":"hostb","data":"127.0.0.1","ttl":"900","type":"a","domainId":"1234"}
      ]
    ]
}

パラメーターと戻り値の形式の別の設定方法

REST URL への「.json」および「.xml」の追加に加えて、MIME タイプ (JSON の場合は application/json、XML の場合は text/xml) を要求の HTTP Accept または Content-Type ヘッダーに入れて渡すことによって、API 呼び出しの戻り値の形式を設定することもできます。

オブジェクト・マスクの使用

objectMask 変数を照会ストリングに追加することによって、API 呼び出し URL でオブジェクト・マスクを作成します。オブジェクト・マスクは、リレーショナル・プロパティーのセミコロンで区切られたリストであり、ピリオドで区切られたリレーショナル・プロパティーがチェーニングされます。照会ストリングのスペースを節約するために、REST オブジェクト・マスクは、照会する API サービスではなく、URL の末尾のデータ・タイプを基準にします。同様に、REST オブジェクト・マスクには mask プロパティーが含まれません。

以下の URL は、アカウントのハードウェア・レコードを、ハードウェアが置かれているデータ・センターと一緒に取得するオブジェクト・マスクを作成します。このオブジェクト・マスクには、アカウントではなく、ハードウェアに関連して取得したいリレーショナル・プロパティーのみが含まれることに注目してください。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter

次の URL は、アカウントのハードウェア・レコードを、そのハードウェアに関連したデータ・センター、オペレーティング・システム、およびネットワーク・コンポーネント・レコードと一緒に取得します。これらのリレーショナル・アイテムはセミコロンで区切られていることに注意してください。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter;operatingSystem;networkComponents

次の URL は、アカウントのハードウェア・レコードを、そのハードウェアに関連したデータ・センター、オペレーティング・システム、オペレーティング・システム・パスワード、およびネットワーク・コンポーネント・レコードと一緒に取得します。チェーニングされたリレーショナル・プロパティーは、ピリオドで区切られます。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter;operatingSystem.passwords;networkComponents

REST API は、SoftLayer の SOAP API や XML-RPC API とはやや異なる方法でオブジェクト・マスクを処理できます。SoftLayer API から取得されるローカル・データ・タイプ・プロパティーをフィルターに掛けるために、REST オブジェクト・マスクを作成できます。マスクでローカル・プロパティーを定義すると、SoftLayer API はマスクをフィルターとして扱い、マスクで指定されたローカル・プロパティーのみを取得します。例えば、次の URL は、アカウントのハードウェア・レコード内の id と hostname プロパティーのみを取得します。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=hardware.id;hardware.hostname

結果制限の使用

resultLimit 変数を照会ストリングに追加することによって、API 呼び出しの結果の数を制限します。resultLimit 変数を、コンマで区切られた次の 2 つの数値に設定します。

  • 結果セットを開始するオプションのオフセット。
  • 呼び出しを制限するための結果の数。

次の URL は、SoftLayer_Account::getOpenTickets メソッドを呼び出して、アカウントでオープンしている最初の 2 つのチケットを取得します。

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/OpenTickets.json?resultLimit=0,2

エラー処理

SoftLayer REST API は、API 呼び出しによって戻されるすべてのエラー・メッセージを含む、単一の error ノードの XML または JSON 出力を戻します。例えば、未知のサービスの URL です。
https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.xml
次のエラーを戻します。

>
   Service does not exist>
>

一方、JSON の場合は次のとおりです。

https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.json

次のエラーを戻します。

{
    "error": "Service does not exist"
}

認証エラー

REST URL の要求時に無効なユーザー名/API キーの組み合わせが使用された場合、SoftLayer REST API は HTTP 401 Unauthorized エラーを戻します。

注意事項

複雑なタイプの指定

XML-RPC と同じように、REST API は、特定パラメーターの拡張複合タイプを判別できません。このような場合は、複合パラメーター・セット内の complexType プロパティーを、メソッドに送信するオブジェクトのタイプに定義する必要があります。

参照 API コンポーネント

サービス

データ・タイプ

メソッド