Language: English

REST

Share this article
  • Digg logo
  • Reddit logo
  • Twitter logo
  • Facebook logo
  • LinkedIn logo
  • StumbleUpon logo

SoftLayer provides a RESTful API in addition to RPC-style API services. Use the REST API in cases where your programming language may not have good SOAP or XML-RPC support but can perform simple HTTP protocol actions and can interpret XML or JSON data.

REST URLs

REST API URLs are structured to easily traverse SoftLayer's object hierarchy. A basic REST request is structured as follows:

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • All REST requests, even private network requests, must be passed through HTTP SSL.
  • Use your API username and key to authenticate your request through HTTP authentication.
  • The base hostname and folder name for a REST request is either api.softlayer.com/rest/v3/ or api.service.softlayer.com/rest/v3/. Use api.service.softlayer.com/rest/v3/ to access the REST API over SoftLayer's private network. It's a more secure way to communicate with SoftLayer, but the system making API calls must be on SoftLayer's private network (either purchased from SoftLayer of logged into SoftLayer's private network VPN).
  • Follow up the base URL with the name of the API service you wish to call, for instance "SoftLayer_Account" or "SoftLayer_Hardware_Server".
  • If your API request requires an initialization parameter then add a slash followed by your init parameter id to your URL.
  • The SoftLayer REST API can return either XML or JSON formatted output. Add ".xml" or ".json" to the end of your request to specify which format you'd like to receive data in.

A request like this calls the getObject() method of the API service you're trying to call. SoftLayer_Account::getObject doesn't require an initialization parameter, so its REST URL looks like this:

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

However, to call the getObject() method for a specific SoftLayer_Hardware_Server record use the following URL, assuming "1234" is the id of the server you wish to retrieve:

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

Call API methods other than getObject() by placing the method's name after your initialization parameter. If your method begins with "get", then remove the word "get" from the method name and convert it's first letter to uppercase. This method can also be used to quickly access an object's relational properties. For instance, the getHardware() method and hardware relational property in the SoftLayer_Account API service can be reached at:

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

Similarly, a server's network components can be reached at the following URL:

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

Chain a combination of initialization parameter ids and relational properties to drill down into specific object components. Every id added will drill into that specific relational property. For instance, if you wish to get server 1234's network component with id 5678 use the URL:

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

And to get that network component's uplink connection:

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

HTTP Request Types

DELETE

Use an HTTP DELETE request to delete an object instead of a service's deleteObject() method. For instance, pass an HTTP DELETE request to the following URL in order to remove domain record 1234 from SoftLayer's DNS servers.

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

GET

Use HTTP GET requests for simple object retrieval and method calls. For instance, retrieve domain record id 1234 with an HTTP GET request to the URL:

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

POST

Use an HTTP POST request to create an object instead of a service's createObject() or createObjects() methods. POST a single JSON or XML structure containing a single element called "parameters" containing your object's skeleton structure and any orther parameters required by your API service's createObject() method. For instance, pass an HTTP POST request with the following data to the following URL in order to create a domain record in SoftLayer's DNS servers.

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

Use an HTTP PUT request to edit an object instead of a service's editObject() or editObjects() methods. PUT a single JSON or XML structure containing a single element called "parameters" containing your object's skeleton structure and any orther parameters required by your API service's editObject() method. For instance, pass an HTTP PUT request with the following data to the following URL in order to edit domain resource record 5678 within domain record 1234 on SoftLayer's DNS servers, changing its data to "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

Passing Method Parameters

Parameters are passed in our REST API by appending each to the path of the URL.
These should be passed in the same order they are listed in the documentation for each method, from top to bottom.

For example SoftLayer_Monitoring_Agent::setActiveAlarmSubscriber requires the userRecordId parameter:

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

Some methods will request a single parameter which is an array such as 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"}
      ]
    ]
}

Alternate Ways to Set Parameter and Return Formats

In addition to adding ".json" and ".xml" to your REST URL you can also set API call return formats by passing a MIME-type (application/json for JSON and text/xmlfor XML) in HTTP Accept or Content-Type headers in your request.

Using Object Masks

Create an object mask in your API call URL by adding an objectMask variable to your query string. Object masks are a semicolon delineated list of relational properties, with chained relational properties separated by periods. In order to save space in the query string, REST object masks are relative to the data type at the end of your URL instead of the API service you're querying. Likewise, REST object masks don't contain a mask property.

The following URL creates an object mask that retrieves an account's hardware records along with the datacenters that hardware is located in. Note that the object mask only contains the relational property we want to retrieve related to hardware, not our account.

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

This URL gets an account's hardware records along with that hardware's associated datacenter, operating system, and network component records. Note that these relational items are separate by semicolons.

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

This URL gets an account's hardware records along with that hardware's associated datacenter, operating system, operating system password, and network component records. Chained relational properties are separated by periods.

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

The REST API can handle object masks in a slightly different way than SoftLayer's SOAP And XML-RPC APIs. REST object masks can be made to filter local data type properties retrieved form the SoftLayer API. If you define a local property in your mask, then the SoftLayer API treats your mask as a filter, and will only retrieve the local properties specified in your mask. For example, this URL retrieves only the id and hostnameproperties in an account's hardware records:

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

Using Result Limits

Limit the number of results in an API call by adding a resultLimit variable to your query string. Set your resultLimit variable to a comma delineated set of two numbers:

  • The offset to begin your result set at.
  • The number of results to limit your call to.

This URL retrieves the first two tickets open on an account, calling the SoftLayer_Account::getOpenTickets method:

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

Error Handling

The SoftLayer REST API returns XML or JSON output with a single error node containing any error messages returned by your API call. For instance, the URL to the nonexistent service:
https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.xml
returns the error:

>
   Service does not exist>
>

While it's JSON equivalent:

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

returns the error:

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

Authentication Errors

The SoftLayer REST API returns an HTTP 401 Unauthorized error if an invalid username / API key combination is used when requesting a REST URL.

Caveats

Specifying Complex Types

As with XML-RPC, the REST API cannot determine extended complex types in certain parameters. In these cases you should define a complexType property in your complex parameters set to the type of object you're sending to your method.

Referenced API Components

Services

Data Types

Methods