Simple Object Access Protocol (SOAP) is built on server-to-server remote procedure calls over HTTP. The data is formatted as XML; this means secure, well formatted data will be sent and received from SoftLayer’s API. This may take a little more time to set up than the REST API but it can be more scalable as you programmatically interface with it. SOAP’s ability to tunnel through existing protocols such as HTTP and innate ability to work in an object-oriented structure make it an excellent choice for interaction with the SoftLayer API.
This post gets pretty technical and detailed, so it might not appeal to our entire audience. If you’ve always wondered how to get started with SOAP API development, this post might be a good jumping-off point.
Authentication
Before you start playing with the SoftLayer SOAP API, you will need to find your API authentication token. Go into your portal account, and click the “Manage API Access” link from the API page under the Support tab. At the bottom of the page you’ll see a drop down menu for you to “Generate a new API access key” for a user. After you select a user and click the “Generate API Key” button, you will see your username and your API key. Copy this API key, as you’ll need it to send commands to SoftLayer’s API.
PHP
In PHP 5.0+ there are built in classes to deal with SOAP calls. This allows us to quickly create an object oriented, server side application for handling SOAP requests to SoftLayer’s API. This tutorial is going to focus on PHP 5.1+ as the server side language for making SOAP function calls. If you haven’t already, you will need to install the soap client for php, here is a link with directions.
Model View Controller
Model-View-Controller or MVC is a software architecture commonly used in web development. This architecture simply provides separation between a data abstraction layer (model), the business logic (controller), and the resulting output and user interface (view). Below, I will describe each part of our MVC “hello world” web application and dissect the code so that you can understand each line.
To keep this entry a little smaller, the code snippits I reference will be posted on their own page: SOAP API Code Examples. Protip: Open the code snippit page in another window so you can seamlessly jump between this page and the code it’s referencing.
Model
The first entry on the API Code Examples page is “The Call Class,” a custom class for making basic SOAP calls to SoftLayer’s API. This class represents our model: The SOAP API Call. When building a model, you need to think about what properties that model has, for instance, a model of a person might have the properties: first name, height, weight, etc. Once you have properties, you need to create methods that use those properties.
Methods are verbs; they describe what a model can do. Our “person” model might have the methods: run, walk, stand, etc. Models need to be self-sustaining, that means we need to be able to set and get a property from multiple places without them getting jumbled up, so each model will have a “set” and “get” method for each of its properties. A model is a template for an object, and when you store a model in a variable you are instantiating an instance of that model, and the variable is the instantiated object.
- Properties and Permissions
Our model has these properties: username, password (apiKey), service, method, initialization parameters, the service’s WSDL, SoftLayer’s type namespace, the SOAP API client object, options for instantiating that client, and a response value. The SOAP API client object is built into php 5.1+ (take a look at the “PHP” section above), as such, our model will instantiate a SOAP API object and use it to communicate to SoftLayer’s SOAP API.Each of our methods and properties are declared with certain permissions (protected, private, or public), these set whether or not outside functions or extended classes can have access to these properties or methods. I “set” things using the “
$this
” variable,$this
represents the immediate class that the method belongs to. I also use the arrow operator (->
), which accesses a property or method (to the right of the arrow) that belongs to$this
(or anything to the left of the arrow). I gave as many of the properties default values as I could, this way when we instantiate our model we have a fully fleshed out object without much work, this comes in handy if you are instantiating many different objects at once. - Methods
I like to separate my methods into 4 different groups: Constructors, Actions, Sets, and Gets:- Sets and Gets
Sets and Gets simply provide a place within the model to set and get properties of that model. This is a standard of object oriented programing and provides the model with a good bit of scalability. Rather than accessing the property itself, always refer to the function that gets or sets the property. This can prevent you from accidentally changing value of the property when you are trying to access it. Lines 99 to the end of our call are where the sets and gets are located. - Constructors
Constructors are methods dedicated to setting options in the model, lines 23-62 of the call model are our constructors. The beauty of these three functions is that they can be copied into any model to perform the same function, just make sure you keep to the Zend coding standards.First, let’s take a look at the
__construct
method on line 24. This is a special magic php method that always runs immediately when the model is instantiated. We don’t want to actually process anything in this method because if we want to use the default object we will not be passing any options to it, and unnecessary processing will slow response times. We pass the options in an array calledSetup
, notice that I am using type hinting and default parameters when declaring the function, this way I don’t have to pass anything to model when instantiating. If values were passed in the$Setup
variable (which must be an array), then we will run the “setOptions”
method.Now take a look at the
setOptions
method on line 31. This method will search the model for a set method which matches the option passed in the$setup
variable using the built inget_class_methods
function. It then passes the value and name of that option to another magic method, the__set
method.Finally, let’s take a look at the
__set
and__get
methods on lines 45 and 54. These methods are used to create a kind of shorthand access to properties within the model, this is called overloading. Overloading allows the controller to access properties quicker and more efficiently. - Actions
Actions are the traditional verbs that I mentioned earlier; they are the “run”, “walk”, “jump”, and “climb” of our person model. We have 2 actions in our model, the response action and the createHeaders action.The createHeaders action creates the SOAP headers that we will pass to the SoftLayer API; this is the most complicated method in the model. Understanding how SOAP is formed and how to get the correct output from php is the key to access SoftLayer’s API. On line 77, you will see an array called Headers, this will store the headers that we are about to make so that we can easily pass them along to the API Client.
First we will need to create the initial headers to communicate with SoftLayer’s API. This is what they should look like:
<authenticate xsi:type="slt:authenticate" xmlns:slt="http://api.service.softlayer.com/soap/v3/SLTypes/"> <username xsi:type="xsd:string">MY_USERNAME</username> <apiKey xsi:type="xsd:string">MY_API_ACCESS_KEY</apiKey> </authenticate> <SoftLayer_API_METHODInitParameters xsi:type="v3:SoftLayer_API_METHODInitParameters" > <id xsi:type="xsd:int">INIT_PERAMETER</id> </SoftLayer_API_METHODInitParameters>
In order to build this we will need a few saved properties from our instantiated object: our api username, api key, the service, initialization parameters, and the SoftLayer API type namespace. The api username and key will need to be set by the controller, or you can add in yours to the model to use as a default. I will store mine in a separate file and include it in the controller, but on a production server you might want to store this info in a database and create a “user” model.
First, we instantiate SoapVar objects for each authentication node that we need. Then we store the SoapVar objects in an array and create a new SoapVar object for the “
authenticate
” node. The data for the “authenticate
” node is the array, and the encoding is typeSOAP_ENC_OBJECT
. Understanding how to nest SoapVar objects is the key to creating well formed SOAP in PHP. Finally, we instantiate a new SoapHeader object and append that to the Headers array. The second header we create and add to the Headers array is for initialization parameters. These are needed to run certain methods within SoftLayer’s API; they essentially identify objects within your account. The final command in this method (__setSoapHeaders
) is the magical PHP method that saves the headers into our SoapClient object. Now take a look at how I access the method; because I have stored the SoapClient object as a property of the current class I can use the arrow operator to access methods of that class through the$_client
property of our class, or thegetClient()
method of our class which returns the client.The Response method is the action which actually contacts SoftLayer’s API and sends our SOAP request. Take a look at how I tell PHP that the string stored in our
$_method
property is actually a method of our $_client property by adding parenthesis to the end of the$Method
variable on line 71.
- Sets and Gets
View
The view is what the user interprets, this is where we present our information and create a basic layout for the web page. Take a look at “The View” section on SOAP API Code Examples. Here I create a basic webpage layout, display output information from the controller, and create a form for sending requests to the controller. Notice that the View is a mixture of HTML and PHP, so make sure to name it view.php that way the server knows to process the php before sending it to the client.
Controller
The controller separates user interaction from business logic. It accepts information from the user and formats it for the model. It also receives information from the model and sends it to the view. Take a look at “The Controller” section on SOAP API Code Examples. I accept variables posted from the view and store them in an array to send to the model on lines 6-11. I then instantiate the $Call
object with the parameters specified in the $Setup
array, and store the response from the Response method as $Result
in line 17 for use by the view.
Have Fun!
Although this tutorial seems to cover many different things, this just opens up the basic utilities of SoftLayer’s API. You should now have a working View to enter information and see what kind of data you will receive. The first service and method you should try is the SoftLayer_Account
service and the getObject
method. This will return your account information. Then try the SoftLayer_Account
service and the getHardware
method; it will return all of the information for all of your servers. Take the IDs from those servers and try out the SoftLayer_Hardware_Server
service and the getObject
method with that id
as the Init
property.
More examples to try: SoftLayer Account, SoftLayer DNS Domain, SoftLayer Hardware Server. Once you get the hang of it, try adding Object Masks and Result Limits to your model.
Have Fun!
-Kevin
- Lilah Brown's Planets, Part II (or, Season II preview) - November 8th, 2009 [November 8th, 2009]
- Snow White needs a bailout - November 8th, 2009 [November 8th, 2009]
- To the moon - November 8th, 2009 [November 8th, 2009]
- S/1 90482 (2005) needs your help - November 8th, 2009 [November 8th, 2009]
- We'll always have Regulus - November 8th, 2009 [November 8th, 2009]
- Orcus Porcus - November 8th, 2009 [November 8th, 2009]
- Kant's Crowded Universe - November 8th, 2009 [November 8th, 2009]
- Look up! - November 8th, 2009 [November 8th, 2009]
- Baby Pictures - November 8th, 2009 [November 8th, 2009]
- Encore: Yelping at Saints - November 8th, 2009 [November 8th, 2009]
- Godspeed - November 8th, 2009 [November 8th, 2009]
- Heavens above! - November 8th, 2009 [November 8th, 2009]
- Homeward bound - November 8th, 2009 [November 8th, 2009]
- Sony Pictures and the end of the world - November 8th, 2009 [November 8th, 2009]
- Thank you from the future - November 8th, 2009 [November 8th, 2009]
- Lunar dreams - November 8th, 2009 [November 8th, 2009]
- The first of the Pluto books! - November 8th, 2009 [November 8th, 2009]
- Don't try to blame it on Rio - November 8th, 2009 [November 8th, 2009]
- Rio roundup - November 8th, 2009 [November 8th, 2009]
- The long road to a Titan storm - November 8th, 2009 [November 8th, 2009]
- Planetary Placemats - November 8th, 2009 [November 8th, 2009]
- Fog! Titan! Titan Fog! (and a peer review experiment) - November 8th, 2009 [November 8th, 2009]
- Millard Canyon Memories - November 8th, 2009 [November 8th, 2009]
- The problem with science - November 8th, 2009 [November 8th, 2009]
- P.S. on the problem with science - November 8th, 2009 [November 8th, 2009]
- How Big is 10 TB? - November 8th, 2009 [November 8th, 2009]
- Showing You Your Servers - November 8th, 2009 [November 8th, 2009]
- Pick Your Partnership: Referral Partners, Resellers and Affiliates - November 8th, 2009 [November 8th, 2009]
- Server Form Factors: Towers v. Rack-Mounts - November 8th, 2009 [November 8th, 2009]
- Lights-Out in the Data Centers - November 8th, 2009 [November 8th, 2009]
- Disruptive Technologies: Virtualization and The Cloud - November 8th, 2009 [November 8th, 2009]
- Know Thy Backups – Part I - November 8th, 2009 [November 8th, 2009]
- Know Thy Backups – Part II - November 8th, 2009 [November 8th, 2009]
- Boo Bash 2009 – Desktop Costume Included! - November 8th, 2009 [November 8th, 2009]
- Why No One Will Talk About “Cloud Computing” in 10 Years - November 8th, 2009 [November 8th, 2009]
- The end of the fall - December 13th, 2009 [December 13th, 2009]
- We Love ‘Server Huggers’ - December 13th, 2009 [December 13th, 2009]
- All About the Cloud: An Interview with Dell’s Cloud Evangelist - December 13th, 2009 [December 13th, 2009]
- Happy Solstice - December 21st, 2009 [December 21st, 2009]
- A ghost of Christmas past - December 31st, 2009 [December 31st, 2009]
- Learning from a Blender - January 5th, 2010 [January 5th, 2010]
- Changing my world - January 6th, 2010 [January 6th, 2010]
- A Server. From Scratch. - January 7th, 2010 [January 7th, 2010]
- The Planet Sand Castle: Upgrade Your Sandbox - January 12th, 2010 [January 12th, 2010]
- Hosting for Haiti - January 20th, 2010 [January 20th, 2010]
- Redefining Value - January 26th, 2010 [January 26th, 2010]
- My Experience as a Newbie at The Planet - January 28th, 2010 [January 28th, 2010]
- Confessions of Another New Planeteer - February 1st, 2010 [February 1st, 2010]
- How I Learned to Stop Worrying and Love Permissions - February 11th, 2010 [February 11th, 2010]
- Where at The Planet is Rachel? - February 15th, 2010 [February 15th, 2010]
- The Planet Storage Cloud: FYI - February 19th, 2010 [February 19th, 2010]
- Meet us in March - February 25th, 2010 [February 25th, 2010]
- The Planet in “The Channel” - March 2nd, 2010 [March 2nd, 2010]
- The Planet Server Challenge - March 13th, 2010 [March 13th, 2010]
- The Definitive Guide to Finding The Planet at SXSW - March 13th, 2010 [March 13th, 2010]
- The SXSW Iron Geek Champion! - March 15th, 2010 [March 15th, 2010]
- Drinking from the Fire Hose - March 16th, 2010 [March 16th, 2010]
- The Fastest Hands at SXSW - March 17th, 2010 [March 17th, 2010]
- System.out.println(“Hello World!”); - March 22nd, 2010 [March 22nd, 2010]
- Westmere – Get it Here - March 23rd, 2010 [March 23rd, 2010]
- Orbit on Your iPhone: A Sign of Things to Come - March 24th, 2010 [March 24th, 2010]
- #ShowMeMyServer 2.0 - March 25th, 2010 [March 25th, 2010]
- Get to Know Your Visitors - March 30th, 2010 [March 30th, 2010]
- The Next Big Thing in Hosting: The Hostatulator - April 1st, 2010 [April 1st, 2010]
- Storage Cloud and the City - April 4th, 2010 [April 4th, 2010]
- American Heart – Why I Walk - April 7th, 2010 [April 7th, 2010]
- The Cake Shouldn’t Be a Lie - April 8th, 2010 [April 8th, 2010]
- April Showers Bring May Flowers - April 9th, 2010 [April 9th, 2010]
- First at The Planet: Nehalem EX 4-Socket Servers - April 15th, 2010 [April 15th, 2010]
- Intel Guest Blog: Xeon 5600 - April 16th, 2010 [April 16th, 2010]
- Inside the Office: A Birthday Surprise - April 18th, 2010 [April 18th, 2010]
- The Planet @ Cloud Expo East - April 19th, 2010 [April 19th, 2010]
- The Planet @ ad:tech SF - April 22nd, 2010 [April 22nd, 2010]
- ad:tech Server Challenge - April 22nd, 2010 [April 22nd, 2010]
- ad:tech Panel: Developing Communities Online - April 23rd, 2010 [April 23rd, 2010]
- The Planet @ Interop Las Vegas - April 27th, 2010 [April 27th, 2010]
- Overflowing With Value: 10TB is Back! - April 28th, 2010 [April 28th, 2010]
- The Cloud is NOT the Revolution - April 29th, 2010 [April 29th, 2010]
- The Importance of Orbit 2.0 - May 5th, 2010 [May 5th, 2010]
- The Planet @ Web 2.0 Expo - May 6th, 2010 [May 6th, 2010]