Time for a REST, Everyone

In our last post we mentioned that our API now supports a REST interface. It's really true, and it's really here! Quoth our new, fancy, manual page:

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

https://:@api.[service.]softlayer.com/rest/v3/
[/initializationParameter].

  • 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.

 

Now that the boring stuff is out of the way here are a few sample calls:

The most basic call in the SoftLayer API is the getObject() method in the SoftLayer_Account API service. It also has the simplest URL in our REST API:

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

 

If you need to retrieve a particular object then append its id number to the end of the URL. This URL retrieves information about the SoftLayer_Hardware_Server record 1234:

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

 

One of the coolest things in our API is how all of our objects relate to each other. Append a relational property to the end of your URL to retrieve that object's related objects. This URL retrieves server 1234's network component records:

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

 

Chain these relational properties as far as you need to go. You can also specify single relational properties by adding its id to the end of the URL. This URL retrieves network component record 5678 from server record 1234:

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

 

Since hardware records relate back to the SoftLayer_Account service, your URL can also relate back to it. Your SoftLayer_Account record has properties for nearly every service available to you, and is handy for providing a truly RESTful interface.

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

 

I'm absolutely loving how well this works. Being able to test API functionality right in my web browser has made troubleshooting a lot easier on me. Our REST interface also supports object creation, edit, and deletion and SoftLayer API specific options like object masks and result limits. Check out our manual page for the scoop. Please give it a whirl and tell us what you think. We've got more good stuff coming your way soon!