Author Archive: Kevin Trachier

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.

Read the full SOAP API Application Development post! »

There have been many books written about website design, and I am not about to take on the challenge of disputing any of them or trying to explain every facet of design. In this short blog, I want to explain what I have come to understand as the modern layout of websites. The term “layout” may have many different definitions, but for this article I am talking about the basic structure of your website, meaning separation of concerns, data transfer from host to client, how to handle changes in data, and when to change your page structure.

Separation of Concerns

It is important when sitting down for the first time to build a website to come up with an outline. Start by making a list of the parts of your website and the functions of those parts. I always start at the base of my web structure and work from there. HTML is always the foundation of a website; it defines the structure and outlines how you will display your data – plain and simple. It doesn’t have to include data or styles, nor does it need to be dynamic … At its essence, it’s a static file that browsers can cache.

Client-side scripting languages like JavaScript will take care of client-side animations and data dispersal, while cascading style sheets (CSS) take care of style and presentation, and server-side scripting languages like PHP or Perl can take care of data retrieval and formatting.

Data Transfer

Where is your data going to come from, and what format it will be in when the client receives it? Try to use a data format that is the most compatible with your scripting languages. I use JavaScript as my primary client side scripting program, so I try to use JSON as my data format, but that’s not always possible when dealing with APIs and transferring data from remote computers. JSON is quickly becoming a standard data format, but XML* is the most widely accepted format.

I prefer to use REST APIs as much as possible, because they sends the information directly on the client, rather than using the server as a proxy. However, if a REST API is not available or if there is a security risk involved, you get the advantage of being able to format the data on the server before pushing it to the client. Try to parse and format data as little as possible on the client side of things, the client should be concerned with placing data.

Changes in Data

In the past, websites were made from multiple HTML documents, each one containing different data. The structure of the pages were the same though, so the data changed, but the code was nearly identical. Later, using server side scripting programs, websites became more dynamic, displaying different data based on variables passed in the URL. Now, using AJAX or script injection, we can load new data into a static webpage without reloading. This means less redundant code, less load on the client, and better overall performance.

Page Structure

It is important when displaying data to understand when to change the structure of the page. I start by creating a structure for my home page – it needs to be very open and unrestricting so I can add pictures and text to build the site. Once the overall loose structure is established, I create a structure for displaying products (this will be more restrictive, containing tables and ordering tools). The idea is to have as few HTML structures as possible, but if you find that your data doesn’t fit or if you spend a lot of time positioning your data, then it might be time to create a new structure.

The Impact of a Modern Layout

Following these steps will lead to quicker, more efficient websites. This is (of course) not a new subject, and further understanding of web layout can be found in Model-View-Controller frameworks. If you find that you spend too much time writing code to interface with databases or place data, then frameworks are for you.

-Kevin

*If you have to deal with XML, make sure to include JavaScript libraries that make it easier to parse, like JQuery.

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.

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

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

“Hello World”
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:

https://api.softlayer.com/rest/v3/SoftLayer_Account.xml

• You will be prompted for your username and API access key
• XML data type output

https://USERNAME:PASSWORD@api.softlayer.com/rest/v3/SoftLayer_Account.json

• Automatic authentication
• JSON data type output

The Request
Here is the basic REST request structure:

https://username:API key@api.service.softlayer.com/rest/v3/serviceName/InitializationParameter.returnDatatype

• All requests are sent via secure transfer (https://)
• Listing your username and API key before the URL allows for automatic HTTP authentication
• Service and serviceName both refer to the web service you are trying to access
• InitializationParameter is 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 returnDatatype with the type you would like to receive.

The Data
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.

REST Basics
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.

-Kevin

What is REST?
“Representational State Transfer,” or REST, is a style of software architecture designed to relate different types of hypermedia to each other for distribution. The basic concept of REST is that a client application can request information from a server in the form of a representation of a resource without actually downloading an entirely new resource. This is how the World Wide Web works.

The World Wide Web
A browser is a client side application which requests information from a server; the server then accepts the request and transfers data back to the browser. The data transferred is not an application; it simply gives instructions to the client-side application (the browser), which then uses those instructions to properly display some information. Downloading information from a server changes the application state of the browser. The result of that change in state is a new website, which is therefore named the new state, so when new websites are downloaded by a browser, it is transferring representational data for a new application state.

How does REST relate to SoftLayer’s API?
SoftLayer’s API has many different avenues for implementation; one of these avenues is simple data transfer using the GET method in HTTP. Hyperlinks are one of the most basic examples of REST in action. When the user clicks on the hyperlink it requests information from the server and responds by transferring back representational data, in this case the data is expressed as either XML or JSON.

What are the disadvantages of using a REST API?
REST requests must contain all information, including authentication, within the URL. This can lead to security threats somewhere down the line. Luckily, SoftLayer allows you to add any number of users to your account, and then restrict their access to specific servers/services. This way your customers can utilize SoftLayer’s API without a security risk to you or each other. They can even create their own users and further restrict access.

What are the advantages of using SoftLayer’s REST API?
Direct client to server communication is the biggest advantage of using REST. The other protocols that SoftLayer uses to communicate data to the API require server-side scripting; this means that you will have to program your websites to use the host server as a proxy for calling SoftLayer functions. With REST you can directly link to the information that you want to display, using XLST or JavaScript to display it. You can also use AJAX with JSONP or script injection to dynamically update your webpage.

REST
The REST archetype is the most natural API for HTTP. This sets it above others in that there are no secondary programs needed to interact with HTTP (like SOAP), which means less computing time and better performance. REST APIs also don’t need to use a proxy server for remote procedure calls. This decreases server load and bandwidth usage and further increases website performance. SoftLayer’s REST API is easy to implement, and with SoftLayer’s tiered user system its security flaws can be eliminated. This is why I prefer SoftLayer’s REST API over the others.

Basic REST function calls are detailed in the SoftLayer Development Network (SLDN) here.

-Kevin

What is SOAP?
“Simple Object Access Protocol” – SOAP is a method and format for sending XML from one server to another via HTTP. SOAP allows you to have remote database servers which supply information to power your website. The best part about SOAP is that it is universal and secure. This means that big companies like SoftLayer can open their databases for you to gather the information that you need to keep your customers up to date. This kind of complete transparency is what makes SOAP (and any other supported API) an invaluable asset to SoftLayer customers. In order to fully understand SOAP, you will need to know about markup languages, namespaces and a little about the protocols used to implement it.

Markup Languages?
The term “markup language” is derived from when teachers/editors would make corrections to a written article, using shorthand for what needed to be corrected. A markup language is just a document with a few special symbols used to separate some text as “markup;” this text can then be used by other programs to perform tasks. Markup languages are declarative programming languages, so they contain data and talk about data, but they don’t actually have instructions about what to do with the data. HTML, XML and LaTeX are all variations of markup languages.

Markup languages can be used for all kinds of different things, but the most common markup language used in web design is Hyper Text or HTML. HTML uses predetermined markup “tags” to describe data for browsers to display; it is the basic building block of all websites. SOAP uses XML to transfer data from server to server.

What is XML?
“Extensible markup language” – XML is a markup language dedicated to presenting data to different applications. Unlike HTML, XML has no dedicated markup tags; instead, you can create any type of tag you want. In XML, the tags describe and define the data that they contain. Applications can easily pull just the data that they need, no matter what is in the document. In this way an XML can be expanded without causing application errors, making it “extensible.” Due to the free form of XML tags, sometimes you want multiple tags to have the same name; this is possible with XML namespaces.

How do XML Namespaces work?
Namespaces are used to group XML elements so that parsing programs won’t confuse different elements that have the same name. Namespaces have to be defined by a “universal resource identifier” or URI; essentially, they have to be universally unique. This is why the WC3 chose to use website URLs as the standard naming convention. This can lead to some confusion when looking at XML namespaces, though. Information is not transferred to or from the websites; they don’t even have to resolve, parsing programs read the URLs as basic text strings. SOAP uses a few pre-determined namespaces to define key information, but the most important thing about SOAP is its ability to work as an RPC-type protocol.

RPC?
“Remote procedure calls” are connections created between two or more servers for the sole purpose of enacting programs or procedures on a remote server. RPCs start at the client, sending a request to the remote server with a procedure name and perameters for the procedure. The request has to be in a very strict format, that way the host server doesn’t have to know anything about the language that the client is using. SOAP makes RPCs over HTTP because it is the most accessible protocol; very few firewalls block HTTP, and SOAP makes use of headers similar to HTTP headers to provide encoding and security information.

So, What is SOAP?
In short, SOAP is a very strictly formatted XML document which uses XML namespaces to define key elements of data, sent via HTTP, in order to enact procedures on a remote server, and sometimes receive data in response to those procedures.

-Kevin

What is AJAX?

Asynchronous JavaScript and XML – AJAX – is what you use to create truly dynamic websites. Ajax is the bridge between application and presentation layers, facilitating lightning fast, instant application of data from the end user to the host and back to the end user. It dynamically changes the data displayed on the page without disrupting the end user or bogging down the client. Although the name is misleading, it is used as a term for any process that can change the content of a web page without unnecessarily reloading other parts of the page.

What are XML HTTP requests?

Passing information from your server to your end user’s browser is handled over HTTP in the form of HTML. The browser then takes that info and formats it in a way the end user can view it easily. What if we want to change some of the data in the HTML without loading a whole new HTML document? That’s where XML comes in. Your web page needs to tell the browser to ask for the XML from the server; luckily, all browsers have a function called XmlHttpRequest(). Once it’s called, it will poll the server for XML data.

Why shouldn’t you use XML HTTP requests?

A long time ago, in a galaxy far, far away, Microsoft invented the XmlHttpRequest() object for Microsoft Exchange Server 2000. As with all first generation technologies, everyone wanted to use it, and some people implemented it differently. IE didn’t even have native support until 2006, and there are still some discrepancies in various browsers when studying the OnReadyStateChange event listener. There is also an issue with cross-domain requests. When the internet was young, JavaScript hackers would steal users’ identity by pulling information from secure websites and posting it to their own, stealing bank account numbers, credit cards, etc. Now that the internet has grown up a bit, people with large networks and many servers have found use for sending data across domains, but it’s still not possible with XML HTTP requests.

What’s an Alternative?

Using JavaScript, you can create client side scripts whose source is built with server side scripts, passing variables in the URL. Here’s an example of a basic web page with local JavaScript, a few checkboxes for human interaction, and a table with some information that we want to change. View source on the page below to see the outline.

Looking at the three JavaScript functions, the first (clearTags) automatically clears out the checkboxes on load, the second (check(box)) makes sure that only one box is checked at a time, the third (createScript) is the interesting one; it uses the createElement() function to create an external JavaScript, the source of which is written in PHP. I have provided a sample script below to explain what I mean. First, we get the variable from the URL using the $_GET super global. Then, we process the variable with a switch, but you might use this opportunity to grab info from a database or other program. Finally, we print code which the browser will translate to JavaScript and execute.

<?PHP
//First we get the variable from the URL
$foo=$_GET['foo'];
//Here's the switch to process the variable
switch ($foo){
case 'foo' : print "var E=document.getElementById('data'); E.innerHTML='bar'; "; break;
case 'fooo' : print "var E=document.getElementById('data'); E.innerHTML='barr'; "; break;
case 'ffoo' : print "var E=document.getElementById('data'); E.innerHTML='baar'; "; break;
case 'ffooo' : print "var E=document.getElementById('data'); E.innerHTML='baarr'; "; break;
default : print "var E=document.getElementById('data');
E.innerHTML='unknown'; ";
}
?>

-Kevin