REST

除 RPC 类型的 API 服务外,SoftLayer 还提供了 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 进行传递。
  • 使用您的 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 的系统)。
  • 在基本 URL 后面加上您要调用的 API 服务名称,例如“SoftLayer_Account”或 “SoftLayer_Hardware_Server”。
  • 如果您的 API 请求需要一个初始化参数,请在 URL 后面添加一个斜杠,并后跟您的初始化参数 ID。
  • 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 关系属性:

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 都将钻取到该特定的关系属性。例如,如果您希望获取 ID 为 5678 的服务器 1234 的网络组件,请使用以下 URL:

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 请求传递到以下 URL,以便从 SoftLayer 的 DNS 服务器中移除域记录 1234。

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

使用 HTTP POST 请求来创建对象(而不是服务的 createObject()createObjects() 方法)。发布单个 JSON 或 XML 结构,它包含一个名为“parameters”的元素
,此元素包含对象的框架结构以及 API 服务的 createObject() 方法所需的所有其他参数。例如,将包含以下数据的 HTTP POST 请求传递到以下 URL,以便在 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() 方法)。放置单个 JSON 或 XML 结构,它包含一个名为“parameters”的元素,此元素包含对象的框架结构以及 API 服务的 editObject() 方法所需的所有其他参数。例如,将包含以下数据的 HTTP PUT 请求传递到以下 URL,以便在 SoftLayer 的 DNS 服务器上编辑域记录 1234 中的域资源记录 5678,将其数据更改为“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

传递方法参数

通过将要传递的所有参数都附加到 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"}
      ]
    ]
}

用于设置参数和返回格式的备用方式

除了将“.json”和“.xml”添加到 REST URL 外,还可以通过在请求中的 HTTP AcceptContent-Type 头中传递 MIME 类型(对于 JSON 为
application/json,对于 XML 为 text/xml),来设置 API 调用的返回格式。

使用对象掩码

通过将 objectMask 变量添加到查询字符串,在 API 调用 URL 中创建对象掩码。对象掩码是关系属性的分号分隔列表(用句点分隔链式关系属性)。为节省查询字符串的空间,REST 对象掩码是与 URL 结尾处的数据类型(而不是所查询的 API 服务)相关。同样,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 和 XML-RPC API 略有不同的方式来处理对象掩码。可以创建 REST 对象掩码,用于过滤从 SoftLayer API 检索的本地数据类型属性。如果在掩码中定义了本地属性,那么
SoftLayer API 会将此掩码视为过滤器,并将只检索此掩码中指定的本地属性。例如,此 URL 将只检索某帐户的硬件记录中的 ID 和主机名属性:

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

使用结果限制

通过将 resultLimit 变量添加到查询字符串,以限制 API 调用中的结果数量。将 resultLimit 变量设置为一组由逗号分隔的两个数字:

  • 结果集开始的偏移量。
  • 要为调用限制的结果数量。

此 URL 将调用 SoftLayer_Account::getOpenTickets 方法,来检索某帐户上已打开的前两个凭单:

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

错误处理

SoftLayer REST API 将返回 XML 或 JSON 输出,其中包含一个错误节点,此节点包含 API 调用所返回的所有错误消息。例如,指向不存在服务的 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 未授权”错误。

警告

指定复杂类型

与 XML-RPC 一样,REST API 也无法确定某些参数中的扩展复杂类型。在这些情况下,应将复杂参数集中的 complexType 属性定义为要向该方法发送的对象的类型。

被引用的 API 组件

服务

数据类型

方法