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

1. getDistanceByZip – Get the distance from one zip code to another
2. getZipsByRadius – Get GPS information within (X) miles of a zip code
3. getLocalTime – Get the local time for a zip code

I am going to describe each function in depth, and give examples of each in a few languages. If you have suggestions to this service, feel free to contact me using the contact form.

About the Service

This web service is provided absolutely free. Please don’t abuse this. If requests start getting out of hand and bringing my server to its knees, I will start limiting the number of queries per user per day. I don’t want to do this, but I do like my server actually serving .

It is an RPC style web service, as it really isn’t complicated and is limited to a very specific audience. It’s also easier for developers to use and understand in comparison to document-literal.

Error Handling – SoapFault

If you receive a SoapFault from any of these services, it will be for one of two reasons:

1. Client – you specified invalid parameters
2. Server – something is wrong with my server (let me know if you get this )

Always use a try-catch block when executing requests. In the event a SoapFault is caught, check to see if it’s a Server or Client error. If it’s a Client error, you can rest assured that there are no results to be returned because of invalid parameters, or there’s just no more data. If it is a Server reason, you might inform your users that “The server is experiencing difficulties” or something.

Optimization (and less bandwidth)

To optimize your runtime experience, download my WSDL. This will save your script tons of time and me bandwidth. Also, unless you are in a development environment, make sure your php.ini value “soap.wsdl_cache” is set to 1. This will cache your WSDL in a temporary directory.

Now, on to the service description.

Getting Distances Between Zip Codes – getDistanceByZip(int zipcode1, int zipcode2)

The parameters for this service is pretty much self-explanatory. In order to successfully retrieve the distance between two zip codes, you should specify two valid zip codes.

It’s important to inform you that this is not road distance! This is in fact calculating the distance based on longitude and latitude. The result is always mileage returned in floating point number format, unless you try to get the distance between non-existing zip codes, at which point a Client SoapFault will be returned. This is a very simple, but useful tool for dating sites, phonebooks, etc. Time for some example code!

$zip1 = 35761; // New Market, AL
 
$zip2 = 12345; // Schenectady, NY
 
try {
 
  $soap = new SoapClient("http://www.phpfever.com/web-services/ZipCode.wsdl");
 
  $distance = $soap->getDistanceByZip($zip1,$zip2);
 
} catch (SoapFault $e) {
 
  print_r($e); // print the exception or do something different
 
}

It’s that simple!

Zip Code Radius Searching – getZipsByRadius(int $zip_code, int $radius, string $return_type, int $start, int $end)

The purpose of this service is getting other zip codes within a specified mileage, by a zip code. For instance, you have a dating service and you want your users to be able to search for matches by zip code. The process flow like this:

1. Get user’s zip code (e.g. via form submission).
2. Send that zip code along with a radius (specified mileage) to the web service.
3. Receive the information from the service.
4. Query against your database with the provided zip codes.

Voila! You now have a list of users by zip code and radius. The cool part about this service is that you can either receive the data by serialized array (PHP only) or XML. I recommend using SimpleXML if you plan to request the document in XML format.

The parameters are very important. You must specify each of them every time. Here are the definitions:

1. int zip_code – this is the zip code to search against
2. int radius – this is the distance in mileage from the zip code. There is no maximum value here although this is limited to the US.
3. string return_type – either XML or ARRAY (case doesn’t matter). If array is chosen, a serialized array will be returned. If XML, obviously XML will be returned. See below for sample XML document.
4. int start – this is the starting point. It actually allows you to do pagination! If you are familiar with MySQL’s LIMIT clause, this is the first number (e.g. LIMIT 0,…)
5. int end – this is the ending point. Reverting back to the MySQL LIMIT clause LIMIT 0,30. This has a maximum value of 500. In other words, you can only receive a maximum of 500 results at any given query. Use the start, end capabilties to paginate!

Click here to download the sample XML document.

Again, the example:

try {
 
 $soap = new SoapClient("http://www.phpfever.com/web-services/ZipCode.wsdl");
 
 $distance = $soap->getZipsByRadius(35761,100,'XML',0,300);
 
} catch (SoapFault $e) {
 
 print_r($e); // print the exception or do something different
 
}

Very simple.

Getting Local Time Based on Zip Code – getLocalTime(int zipcode,string format)

This simple, yet powerful service allows you to get the local date/time of a specific zip code. The date and time fields are two separate elements for easier parsing.

Example:

 
try {
  $soap = new SoapClient('http://www.phpfever.com/web-services/ZipCode.wsdl');
  $time = $soap->getLocalTime(35761);
} catch (SoapFault $e) {
  print_r($e);
}

That’s it! I will be posting more example code in different languages as I go.