REST

除了 RPC 樣式的 API 服務之外,SoftLayer 還提供 RESTful API。如果您的程式設計語言沒有好的 SOAP 或 XML-RPC 支援,但可執行簡單的 HTTP 通訊協定動作,並可解譯 XML 或 JSON 資料,在這樣的情況下,請使用 REST API。

REST 網址

REST API 網址已經過結構化,可以輕鬆遍訪 SoftLayer 的物件階層。基本 REST 要求的結構如下:

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • 所有 REST 要求,即使是私密網路要求,都必須透過 HTTP SSL 傳遞。
  • 使用您的 API 使用者名稱和金鑰,透過 HTTP 鑑別來鑑別您的要求。
  • REST 要求的基本主機名稱和資料夾名稱是 api.softlayer.com/rest/v3/api.service.softlayer.com/rest/v3/。使用 api.service.softlayer.com/rest/v3/ 表示透過 SoftLayer 的私密網路存取 REST API。這是與 SoftLayer 通訊較為安全的方式,但發出 API 呼叫的系統必須是在 SoftLayer 的私密網路中(可向 SoftLayer 購買或登入 SoftLayer 私密網路的 VPN)。
  • 以您想要呼叫的 API 服務名稱(例如,"SoftLayer_Account" 或 "SoftLayer_Hardware_Server")完成基本 URL。
  • 如果 API 要求需要起始設定參數,則在網址中加入斜線,其後接著您的起始參數 ID。
  • SoftLayer REST API 會傳回 XML 或 JSON 格式化輸出。在要求的尾端加入 ".xml" 或 ".json",可指定接收資料所使用的格式。

這樣的要求會呼叫您嘗試呼叫的 API 服務的 getObject() 方法。SoftLayer_Account::getObject 不需要起始設定參數,因此它的 REST 網址類似下面這樣:

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

但是,若要對特定的 SoftLayer_Hardware_Server 記錄呼叫 getObject() 方法,請使用下列網址,並假定 "1234" 是您要擷取的伺服器的 ID:

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

呼叫 getObject() 以外的 API 方法時,請在起始設定參數之後放置方法的名稱。如果方法的開頭是 "get",則從方法名稱中移除 "get" 這個字,並將它的第一個字母轉換成大寫。此方法也可以用來快速存取物件的關聯式內容。例如,可從下列網址中存取 getHardware() 方法和 SoftLayer_Account API 服務中的 hardware 關聯式內容:

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

同樣地,可從下列網址中存取伺服器的網路元件:

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

鏈結起始設定參數 ID 和關聯式內容的組合,以往下探查特定的物件元件。所加入的每一個 ID 將探查至該特定的關聯式內容。例如,若您想要取得伺服器 1234 的網路元件(其 ID 為 5678),請使用下列網址:

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

以及取得該網路元件的上行鏈路連線:

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

HTTP 要求類型

DELETE

使用 HTTP DELETE 要求而非服務的 deleteObject() 方法來刪除物件。例如,將 HTTP DELETE 要求傳遞至下列網址,從 SoftLayer 的 DNS 伺服器中移除網域記錄 1234。

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

GET

使用 HTTP GET 要求進行簡易物件擷取和方法呼叫。例如,透過對該網址的 HTTP GET 要求來擷取網域記錄 ID 1234:

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

POST

使用 HTTP POST 要求而非服務的 createObjects()createObjects() 方法來建立物件。公佈 (POST) 包含單一元素 "parameters" 的單一 JSON 或 XML 結構,該元素包含您物件的架構結構及 API 服務的 createObject() 方法所需要的任何其他參數。例如,將含有下列資料的 HTTP POST 要求傳遞至下列網址,以便在 SoftLayer 的 DNS 伺服器中建立網域記錄。

{
    "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

使用 HTTP PUT 要求而非服務的 editObject()editObjects() 方法來編輯物件。放置 (PUT) 包含單一元素 "parameters" 的單一 JSON 或 XML 結構,該元素包含您物件的架構結構及 API 服務的 editObject() 方法所需要的任何其他參數。例如,將含有下列資料的 HTTP PUT 要求傳遞至下列網址,以便在 SoftLayer 的 DNS 伺服器上編輯網域記錄 1234 內的網域資源記錄 5678,將其 data 變更為 "10.0.0.1"。

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

傳遞方法參數

透過將每一個參數附加至網址的路徑中,在 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"}
      ]
    ]
}

設定參數和傳回格式的替代方法

除了將 ".json" 和 ".xml" 加入 REST 網址中之外,您還可以透過在您的要求的 HTTP AcceptContent-Type 標頭中傳遞 MIME 類型(對於 JSON 是 application/json,對於 XML 是 text/xml),來設定 API 呼叫的傳回格式。

使用物件遮罩

透過在查詢字串中加入 objectMask 變數,在 API 呼叫網址中建立物件遮罩。物件遮罩是以分號區隔的關聯式內容清單,所鏈結的關聯式內容是以句點分隔。為了節省查詢字串的空間,REST 物件遮罩會相對於您網址結尾的資料類型,而非您要查詢的 API 服務。同樣地,REST 物件遮罩不包含 mask 內容。

下列網址建立物件遮罩來擷取帳戶的硬體,以及硬體所在的資料中心。請注意,物件遮罩只包含我們想要擷取的關聯式內容,是與硬體相關,而非帳戶。

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

這個網址取得帳戶的硬體記錄,以及該硬體的關聯資料中心、作業系統和網路元件記錄。請注意,這些關聯式項目是以分號分隔。

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

這個網址取得帳戶的硬體記錄,以及該硬體的關聯資料中心、作業系統、作業系統密碼和網路元件記錄。鏈結的關聯式內容是以句點分隔。

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

REST API 可以稍微不同於 SoftLayer 的 SOAP 和 XML-RPC API 方式來處理物件遮罩。REST 物件遮罩可用來過濾從 SoftLayer API 擷取的本端資料類型內容。如果您在遮罩中定義區域內容,則 SoftLayer API 會將遮罩視同過濾來處理,只會擷取在您遮罩中指定的區域內容。例如,這個網址只擷取帳戶的硬體記錄中的 id 和 hostname 內容:

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

使用結果限制

透過將 resultLimit 變數加入查詢字串中,來限制 API 呼叫中的結果數。請將 resultLimit 變數設為以逗點區隔、兩個為一組的數字:

  • 開始結果集的偏移。
  • 限制呼叫的結果數。

這個網址透過呼叫 SoftLayer_Account::getOpenTickets 方法來擷取在帳戶上開立的前兩個問題單:

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

錯誤處理

SoftLayer REST API 傳回的 XML 或 JSON 輸出含有單一 error 節點,其包含 API 呼叫傳回的任何錯誤訊息。例如,此不存在服務的網址:
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 網址時使用無效的使用者名稱 / API 金鑰組合,則 SoftLayer REST API 傳回「HTTP 401 未獲授權」錯誤。

警告

指定複式類型

就像 XML-RPC 一樣,REST API 無法決定某些參數的延伸複式類型。在這些情況下,您應該在複式參數集內,將 complexType 內容定義為您要傳送至方法的物件類型。

參照的 API 元件

服務

資料類型

方法