Web services bring with them some huge advantages. Data is packaged via HTTP or HTTPS and can usually bypass firewalls since port 80 and 443 are commonly allowed open. This plays a big role where intranet systems need to communicate but have a very strict set of firewall rules. An example might be an Oracle DB link needing to reach a MySQL server. Typically this is a daunting task as you have to go through the bureaucracy of getting the proper ports opened, get added to one or more access-controlled lists, receive/provide access privileges at the database level, etc. Then there is the issue of direct access to data, either by view, table or procedure; the list goes on and on.

Most of these problems can be eliminated by the use of web services. This article’s objective is to explain, at a high-level, when, why and how web services are used.

Table of Contents

1. Web Service Overview
2. Authoritative Data Control
3. Multi-Data Access Web Services
4. Business Platform Web Services
5. Web Service Technologies and Common Terms

Web Service Overview

As stated above, web services can be as simple as an API call similar to Google Maps where a client requests an action be performed and data sent/received. You may have a system that displays a location based on a zip code related to a row in the database, and you want to display that precise location on a map to the end user. You would send a request to the provider, Google in this case, and it would return a map based on that criteria. This is a very common form of web services: a client requests data from a provider and the provider returns data based on the client’s request.

Authoritative Data Control

A not-so-common form of web services is authoritative data control. This is when two or more systems have a unique set of data, but share a common subset of data elements.

Take the automotive industry, for example, and mix in auto insurance and the DMV (Department of Motor Vehicles). All three sources might share a car’s VIN (Vehicle Identification Number), make, model, license plate number, and insurance policy number. Today, I’ll bet there are few, if any, systems setup to share this type of authoritative data. Instead, you are forced to give this information to each source. Let’s analyze.

When you pull into a car lot, the following data elements are known prior to even selecting your car:

1. VIN
2. Make
3. Model

Identifying the origin of data is extremely important. This will define the business logic behind identifying authoritative data sources. We know the VIN is unique to every car on the road, so it will act as our “primary” or “unique” key. All sources that need information relating to a single vehicle can use this to request and send data. The make and model are absolutely not unique, so they will be accompanied by a VIN number. If you are familiar with databases, you should be seeing a pattern here.

Now you have purchased the car of choice and ready to get on the road! Wait! You need a temporary license tag! This information will make your car legal on the road for a short period of time. In order to get this, however, you will need insurance! You call up your insurance agent or company, and inform them of the new purchase. They ask you for the automobiles VIN, and make a request to the dealer/manufacturer and get the information relating to the car. They provide you with your policy number, which you hand off to the dealer. They register your car with the DMV by providing the VIN and insurance policy number. Yay! You can drive off the lot.

Now that you’ve had the car for a few days, you need to get a permanent license plate. Why not visit the DMV’s website and order it? You visit the website, enter your VIN number and pay for your plate. The DMV then pulls the information, grabs a license plate, sends the updated registration information to the dealer and insurance and sends your license plate. Isn’t it a perfect world!! Well, not exactly.

The difficult part about web services is not the technology; it’s the business logic. The DMV may think it should house all of the data and provide it to the insurance and dealer while the dealer thinks it should own it because it’s the originating source. It takes dedication and sacrifice by those who make business decisions in order for scenarios like this to happen.

Multi-Data Access Web Services

This is another common scenario that is rarely addressed with web services: a single data source that multiple systems access. This situation is a no-brainer if you are building a new system, but can be hell if you are converting existing ones.

Let’s say you have a system that has a massive PostgreSQL database with views, procedures and tables and has a relatively old or unstable platform. You have five systems that all use their own views and procedures to access and manipulate the data, and they are all mature sites.

This is a very hard situation to convert to web services, but it has its benefits. What if you’re ready to (or have to) convert this system to MySQL? You now have five codebases to change, views and stored procedures to reverse-engineer and months of development on your hands.

Now, imagine if you had a single source where a series of web services provide the data and same functionality as the views and procedures from the database. All five systems manipulate and read the data from those web services. You have only one place to change the code once the database is converted over to MySQL. All of those views and procedures probably wouldn’t be necessary if these services provided that functionality.

Business Platform Web Services

A Business Platform Web Service (that’s what I call it) is when most or all aspects of a business are driven by web services. This is a very complex scenario and requires a mature set of programs. You should have fail-overs in place for this, but if a single program fails, panic would arise in the programmer’s den.

In order to illustrate this, I will give you a fictitious company and scenario:

Example Scenario

A tire company called “ABC Tires” is located in the state of Arizona, and resells its tires to 200 stores in Tennessee, Alabama, Florida and Texas. This tire company provides a combined average of 500,000 tires per month to all of its locations. The tire factory has enough employees to produce that amount and no more. It is crucial that each of these resellers not get backlogged on orders or tires will not be delivered on time and business will be lost.

To make things a little more complicated, tires are only shipped out in bulks of 5,000, and this tire company uses 4 different freight companies to deliver its tires. Each of these freights attend to other clients, so they need as much notification as possible for pickup.

Take not of the diagram below:

Let’s run through the scenario:

1. Reseller makes tire sale. Point-of-sale system has a web service hook and sends the request to the provider.
2. Provider tracks sale and sends request for tire to be made.
3. Plant creates tire and sends it to the warehouse. It then informs the provider that the tire has been created/replaced.
4. Provider checks the database for the total tires in the warehouse. If the count is getting close to 5,000, it sends a request to freight providers until a confirmed shipment is setup. The freight returns the pickup time back to the provider.
5. Provider informs reseller(s) of shipment. The reseller can then hold tires for potential customers and can provide a date for installation/purchase.
6. Freight delivers tires to reseller(s).

The are many advantages to this setup: single data source, automated work flow and no firewall rules to worry about. Setting up a system like this requires time, planning and dedication on the part of the company implementing it.

There are other examples of more advanced web service systems where UDDIs (Universal Description, Discovery and Integration), an XML-based registry for businesses worldwide to list themselves, are involved but that is beyond the scope of this article. Let’s take a look at some technologies associated with web services.

Web Service Technologies and Common Terms

There are many technologies associated with web services, and I will attempt to touch some of them. I will not go in-depth on any single technology as I will reserve a future article for them.

Specifications¹

• WS-Security – Defines how to use XML Encryption and XML Signature in SOAP to secure message exchanges, as an alternative or extension to using HTTPS to secure the channel.
• WS-Reliability – An OASIS standard protocol for reliable messaging between two Web services.
• WS-ReliableMessaging – A protocol for reliable messaging between two Web services, issued by Microsoft, BEA and IBM it is currently being standardized by the OASIS organization.
• WS-Addressing – A way of describing the address of the recipient (and sender) of a message, inside the SOAP message itself.
• WS-Transaction – A way of handling transactions

Styles of Use¹

Remote procedure calls – RPC Web services present a distributed function (or method) call interface that is familiar to many developers. Typically, the basic unit of RPC Web services is the WSDL operation.

The first Web services tools were focused on RPC, and as a result this style is widely deployed and supported. However, it is sometimes criticised for not being loosely coupled, because it was often implemented by mapping services directly to language-specific functions or method calls. Many vendors felt this approach to be a dead end, and pushed for RPC to be disallowed in the WS-I Basic Profile.

Service-oriented architecture – Web services can also be used to implement an architecture according to Service-oriented architecture (SOA) concepts, where the basic unit of communication is a message, rather than an operation. This is often referred to as “message-oriented” services.

SOA Web services are supported by most major software vendors and industry analysts. Unlike RPC Web services, loose coupling is more likely, because the focus is on the “contract” that WSDL provides, rather than the underlying implementation details.

Representational state transfer – Finally, RESTful Web services attempt to emulate HTTP and similar protocols by constraining the interface to a set of well-known, standard operations (e.g., GET, PUT, DELETE). Here, the focus is on interacting with stateful resources, rather than messages or operations. RESTful Web services can use WSDL to describe SOAP messaging over HTTP, which defines the operations, or can be implemented as an abstraction purely on top of SOAP (e.g., WS-Transfer).

WSDL version 2.0 offers support for binding to all the HTTP request methods (not only GET and POST as in version 1.1) so it enables a better implementation of RESTful Web services[1]. However support for this specification is still poor in software development kits, which often offer tools only for WSDL 1.1.

¹ – http://en.wikipedia.org/wiki/Web_service

The majority of the time, developers need to read/write XML files without complex features such as advanced namespacing and XSD validation. It seems that opening an XML file, reading and using the content takes forever as you constantly need to reference hundreds of pages of documentation, Google examples of each method or function in the documentation; it never ends.

Since the release of PHP5, SimpleXML has been available for creating and editing XML files or strings. Don’t let the name fool you, it doesn’t represent the simplicity of its capabilities. It does, however, mean the implementation of this extension is simple! PHP has other XML capabilities such as DOM, XMLWriter and XMLReader in the event you need those advanced features not offered by the native SimpleXML extension.

Configuring PHP to Use SimpleXML

SimpleXML is an extension that was added as of PHP 5 and requires no special libraries. If for some reason you wish not to have SimpleXML available to your PHP configuration, you can disable it at compile-time using --disable-simplexml. The primary class you will work with is called SimpleXMLElement.

There are Four Ways to Get an Instance of SimpleXMLElement:

1. simplexml_load_file – Load an XML document from a file. You may also access a remote file (HTTP for example).
2. simplexml_load_string – Load and XML string. Please keep in mind the XML needs to be well-formed.
3. SimpleXMLElement - Directly instantiate the SimpleXMLElement class. This requires a parameter starting the XML document. If you directly instantiate this class, you are typically using SimpleXML for XML output.
4. simplexml_import_dom – Returns and instance of SimpleXMLElement from a DOM object. That’s right, you can bring over that advanced object and make life simple!

Sample XML File Used

The following XML data will be contained in the referenced “test_file.xml”:

<?xml version="1.0" encoding="ISO-8859-1"?>
<cars>
	<make name="Ford">
		<model>Mustang</model>
	</make>
	<make name="Honda">
		<model>Accord</model>
	</make>
</cars>

Loading XML Data Using simplexml_load_file

This function is typically used for loading XML data either from a file, or a remote call. In this example, we will load a flat XML file:

<?php
// Location of the XML file on the file system
$file = 'test_file.xml';
$xml = simplexml_load_file($file);
?>

That’s it. No need to clean anything up, PHP will take care of that for you.

Loading XML Using simplexml_load_string

<?php
// XML String
$xml = '
<?xml version="1.0" encoding="ISO-8859-1"?>
<cars>
	<make name="Ford">
		<model>Mustang</model>
	</make>
	<make name="Honda">
		<model>Accord</model>
	</make>
</cars>
';
$xml = simplexml_load_string($xml);
?>

Pretty easy, huh? This function loads an XML string and returns and instance of SimpleXMLElement. You could also directly instantiate the SimpleXMLElement class a similar way, as demonstrated below.

Loading XML Using the SimpleXMLElement Class

<?php
$xml = '
<?xml version="1.0" encoding="ISO-8859-1"?>
<cars>
	<make name="Ford">
		<model>Mustang</model>
	</make>
	<make name="Honda">
		<model>Accord</model>
	</make>
</cars>
';
$xml = new SimpleXMLElement($xml);
?>

It’s your choice on using this method, or simplexml_load_string.

Loading XML Data Using simplexml_import_dom

<?php
$xml = '
<?xml version="1.0" encoding="ISO-8859-1"?>
<cars>
	<make name="Ford">
		<model>Mustang</model>
	</make>
	<make name="Honda">
		<model>Accord</model>
	</make>
</cars>
';
$dom = new DOMDocument;
$dom->loadXML($xml);
$xml = simplexml_import_dom($dom);
?>

This is handy when you are working with the advanced XML features of DOM. When you’re ready to move from those precocious features, just load the DOM object into simplexml_import_dom, and start programming the easy way!

Loading XML Data Using simplexml_load_file

<?php
$file = 'test_file.xml';
$xml = simplexml_load_file($file);
/*
The $xml object now has the top, parent node <cars>
All nodes are referenced as properties, and node attributes are within an associative array in each of those properties.
If there are multiple nodes with the same name (<make> in this example), you will need to specify the index value to reference.  This is done as an array index.  The following code refences the "name" attribute in the first <make> node
*/
echo $xml->make[0]['name'];
// Prints out "Ford" (without quotes)
?>

The above example print out “Ford”. We referenced the first node, and then printed out the “name” attribute. Now, let’s print out “Mustang” from the node.

<?php
$file = 'test_file.xml';
$xml = simplexml_load_file($file);
echo $xml->make[0]->model;
// Prints out "Mustang" (without quotes)
?>

Reading XML doesn’t get any easier. The object-oriented design provided by SimpleXML makes code very elegant and maintainable.

The above examples assume you know exactly which node, down to the index, that contains the data you need to access. In the real world, this is an unlikely scenario. Normally, a developer knows the node names they are working with, but do not know (nor care) as to the number of those nodes.

Just like with normal arrays, we can count the number of elements. We will do this prior to iterating over the node. Let’s iterate!

<?php
$xml = '
<?xml version="1.0" encoding="ISO-8859-1"?>
<cars>
	<make name="Ford">
		<model>Mustang</model>
	</make>
	<make name="Honda">
		<model>Accord</model>
	</make>
</cars>';
$xml = simplexml_load_string($xml);
if (count($xml->make) > 0) {
    foreach ($xml->make as $node) {
        // This prints out each of the models
    	echo $node->model.chr(10);
    }
}
?>

Important Information Regarding Values Returned from SimpleXML

If you have debugged any of these examples, you would have noticed that everything, nodes and attributes, are an instance of SimpleXMLElement. This may or may not be a feature in your opinion, but it’s the nature of SimpleXML. If you plan on storing any of these node/attribute values, you will need to typecast them:

<?php
$xml = 'test_file.xml';
$xml = simplexml_load_file($xml);
$value_to_store = (string) $xml->make[0]->model;
// This converts the "Mustang" SimpleXMLElement object to a string, making it disk storable.
?>

You should certainly keep this in mind as you are working with this extension.

Writing XML with SimpleXML

Writing or producing XML is just as easy as reading it. While you can add additional data to existing XML files, the examples in this section will create fresh XML data. In part two, we will discuss more advanced options such as DOM, CDATA and namespaces. Now, on to writing XML data.

You will quickly learn that SimpleXML expects well-formed XML. There are two PHP functions you should familiarize with if you are not already:

1. utf8_encode – encode a string with UTF-8 standards.
2. htmlspecialchars – encode HTML characters with their proper entities.

You will need to use htmlspecialchars followed by utf8_encode to ensure proper data encoding. The following example illustrates using this technique to ensure proper XML output:

<?php
$xml = new SimpleXMLElement('<cars></cars>');
$make = $xml->addChild('make');
$make->addAttribute('name','Ford');
$make->addChild('model',htmlspecialchars(utf8_encode($some_db_variable)));
$xml->asXML();
// This will output the XML
?>

In order to create a new instance of SimpleXMLElement for writing, you will need to specify the top parent node. No need for the XML declaration, SimpleXML will add this for you. In the above example, we ensured that data coming from a database variable had non-UTF8 encoded characters encoded, and HTML entities properly converted. We also introduced a few additional methods. Let me explain:

The addChild method adds a new child to an existing node. This takes an optional second parameter of the value to place inside that node.

Each time you create a new child, a reference to the SimpleXMLElement is returned for use. Here, you can add additional child nodes, attributes and more. The initial SimpleXML object ($xml in the above example) contains the primary instance. You will use this object to output the data.

The addAttribute method adds an attribute to a node. If you aren’t sure of the data being added to the attribute (and just to be safe), you should also encode that value.

The asXML method saves/outputs the XML to the proper buffer. If you specify a file name in this method, the XML will be written to it. Here is an example:

<?php
$xml = new SimpleXMLElement('<cars></cars>');
$make = $xml->addChild('make');
$make->addAttribute('name','Ford');
$make->addChild('model',htmlspecialchars(utf8_encode($some_db_variable)));
$xml->asXML('test_file.xml');
// This will save the XML to a file called test_file.xml
?>

Conclusion

Through examples and definitions, you have familiarized yourself with the basics of SimpleXML. In part two (which is written yet), I will explain more advanced features of SimpleXML and DOM.

If you have any questions, feel free to post comments.

Will