API Basics: REST API – “Hello World”Posted by Kevin Trachier in SoftLayer, Technology, Tips and Tricks
Learning SoftLayer’s API
When I first started to look at SoftLayer’s API, I favored the SOAP programming interface because I liked the strictly formatted XML responses, the good separation of concerns (using the server as proxy for data retrieval) and the increased security. All of these are great reasons to use the SOAP interface, but once I saw how easy and direct the REST interface is, I decided that I would use it as my cornerstone for learning the SoftLayer API.
Although the REST software archetype is a difficult concept to explain, its practice has become natural to those of us who use the internet daily. Imagine that the information that you want to know is saved as a web page somewhere and all you have to do is type in the URL, it will prompt you for a username and password, and you will see the information that you requested.
Before making a request you will need to find your API authentication token. To do this, log into your customer account and click API under the Support tab. Click the “Manage API Access” link. At the bottom of the next page you will see a drop-down menu that says “Select a User” and above it a tag that says “Generate a new API access key.” Select a user and click the “Generate API Key” button. You will see your username and the generated API key for that user. Copy this API key, as you’ll need it to send commands SoftLayer’s API.
Unfortunately, there is no specific “Hello World” command in SoftLayer’s API, but there are some commands that are very simple and don’t require any variables, like the
getObject() method. APIs are like component libraries, split into web services and methods of that service. The SLDN has a full list of SoftLayer’s web services to choose from. I am going to use the
getObject() method from the
SoftLayer_Account service in this example:
- You will be prompted for your username and API access key
- XML data type output
- Automatic authentication
- JSON data type output
Here is the basic REST request structure:
- All requests are sent via secure transfer (https://)
- Listing your
API keybefore the URL allows for automatic HTTP authentication
serviceNameboth refer to the web service you are trying to access
InitializationParameteris only used if the method you are calling requires an initialization Parameter
- SoftLayer’s REST API can respond with either JSON or XML data types; replace
returnDatatypewith the type you would like to receive.
Looking at the first link above, your browser should be able to output the response data in XML format, showing information about your account. More information about the format of the data can be found on the SLDN wiki.
When you start integrating this into a website you will want to get/make a function or library to handle advanced requests and to properly receive and disperse the response; I recommend using JQuery. This is the most basic example of a function call for SoftLayer’s API, I hope that it will help you get a feel for the information that you will need to pass to our server and the kind of response that you will receive.