Posts Tagged 'Html'

August 23, 2011

SOAP API Application Development 101

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 called Setup, 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 in get_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 type SOAP_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 the getClient() 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.

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

June 28, 2011

Modern Website Design: Layout

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.

February 2, 2011

API Basics: What is SOAP?

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

January 11, 2010

Stop Using Internet Explorer 6!

Let me start by saying this… I hate Internet Explorer 6 (IE6). I really do.

Internet Explorer 6 was born on August 27, 2001. The browser was released in conjunction (well, a little after) with Windows XP as a major upgrade from Internet Explorer 5.5. From those humble beginnings in 2001, IE6 has continued to stay alive mostly because of the continued support/use of Windows XP and web-based applications built specifically for IE6.

Here are a few reasons IE6 is a big pile of junk:

  • Numerous security issues.
  • The inability to support CSS version 2 fully.
  • No support for alpha transparency in PNG images.
  • Quirks Mode, which emulates IE5.5.
  • No tabbed browsing.
  • It’s OLD!

So what makes a good browser!?

  • Full CSS 2+ support.
  • HTML/JavaScript W3C standards compliancy.
  • HTML/JavaScript performance improvements.
  • All new browsers utilize tabbed browsing.
  • Some new browsers (such as Google Chrome) have “Task Managers” that can allow you to destroy certain tabs that may have become unresponsive by a web site.
  • Support for HTML 5.

If you’re still using IE 6, consider upgrading to a new browser such as Mozilla FireFox, Google Chrome, Apple Safari, or a newer version of Microsoft Internet Explorer. You’ll make yourself and web developers around the world so happy!

Categories: 
Subscribe to html