Section 6.1. Web Service | Ajax Design Patterns

6.1. Web Service

API, HTTP, Microcontent, REST, RPC, Share, SOAP, Platform

Figure 6-1. Web Service

6.1.1. Goal Story

In a financial forecasting app, Tracy runs an algorithm to forecast the next four interest rates. The browser script uploads the parameters to an "Interest Rate Forcaster" web service, which eventually outputs a concise list of future rates, free of any HTML markup: 4.5, 3.4, 4.0, 4.1.

6.1.2. Problem

What will Ajax Apps call on the server?

6.1.3. Forces

Ajax Apps can access the server directly and require well-scoped services instead of the conventional-style scripts that output an entire HTML page.
Many organizations like to expose their functionality and data for third parties to access. The API needs to be clean and easy to use.

6.1.4. Solution

Expose server-side functionality as fine-grained, easy-to-use Web Services. "Web Service" is an overloaded term, and the Ajax Patterns use a fairly broad definition:

A Web Service is a standard HTTP service.
A Web Service has a well-defined, consistent interfaceinput and output assumptions, message formats, and exception handling are all clearly understood by its developers and ideally documented in some manner.
A Web Service accepts fine-grained input parameters and outputs fine-grained responses, such as an XML document, a simple string, or a snippet of HTML. If it outputs an entire HTML document, it's probably not a Web Service.

Under this definition, there is considerable flexibility involved in creating a Web Service:

A Web Service might be open to the public, might be protected by a secure authentication mechanism, or might be hidden from the public by a firewall.
A Web Service might be built by a tool or handwritten.
A Web Service might use messages according to any protocol, such as SOAP, or might use custom messages.

Deciding on all these things is the main task involved in creating a Web Service.

Web services are the latest in a long tradition of distributed computing, with technologies like SunRPC, CORBA, and EJB along the way. They've arisen quite separately from Ajax, as a general-purpose way to expose services to interested clients. These clients are usually standalone processes with no user interface as well as desktop clients and web server scripts. Until recently, they were irrelevant to anything inside a web browser, which could only communicate with services capable of returning an entire HTML page. But thanks to remoting technologies, JavaScript can now make use of such services. Indeed, a clean Web Service is actually the best thing for remoting technologies to callit makes the call easier, and having a fine-grained response is good for the response handler. Thus, there's a strong synergy between Ajax and web services.

Here's the PHP code for a one-liner web service to perform a sum (imaginative, I know):

   <?     echo $_GET["figure1"] + $_GET["figure2"];   ?>

You can try the service by entering http://ajaxify.com/run/xmlHttpRequestCall/sumGet.phtml?figure1=5&figure2=10 in your browser's address bar. The entire response will be "15." As the example shows, a web service's response can be as simple as a single value. Other times, it might be some HTML, but even then, it will usually only be a snippet rather than an entire page. For example, the above service could be refactored to show the result as a heading:

   <?     echo "<h1>" . ($_GET["figure1"] + $_GET["figure2"]) . "</h1>";   ?>

A collection of related services like these forms an HTTP-based API that exposes server functionality. Most Ajax Apps will access the API from the browser via the XMLHttpRequest Call and alternative remoting techniques. In addition, third parties can access Web Services and use them for their own applications, web or not.

This section introduces only the concept of web services. There are a number of decisions you need to make when designing such services for your own application. Will the service output XML to be processed in the browser, HTML to be displayed directly, or some other format? How will the URLs look? What sort of input will it take? All these issues are discussed in Chapter 9.

6.1.5. Decisions

6.1.5.1. How will the web service be used?

The single most important decision about a web service, as with any form of API, is to know how it will be used. In particular, will it be available for third-parties as a generic interface to your system, or are you developing it purely for an Ajax browser app to access? If the latter, then you might want to practice feature-driven development and let the browser app drive web service designsee Simulation Service (Chapter 19).

If there are third parties involved, it becomes a balancing act between their needs and the needs of your browser app. Since they will probably be accessing your server from more powerful environments than the average web browser, you might need to add some redundancy to support each type of client. The API for third parties might be more general, whereas the browser sometimes needs an API that knows something about the application. In an extreme case, it tracks application state and outputs the actual HTML to be shown to the user.

6.1.5.2. How will you prevent third-party usage?

Web services are seen as having a kind of synergy with Ajax, as Ajax Apps can talk to the same interface already being offered to third-party clients. However, sometimes you want the web service to be closed to third parties. That's going to be difficult on the public Web, since pretty much anything a browser can access will also be available to third-party clients. So, you might have spent ages designing a nice, clean web service to make browser scripting as painless as possible, only to discover that third parties are reaping the benefits. There's no magic bullet, but here are a few suggestions:

Require users to be logged in, with an authenticated email address, in order for the application to make use of web services. You can then use cookies or upload unique session IDs to authenticate the user.
Consider using a system like Captcha (http://www.captcha.net/), where the user is forced to perform a challenge that should be about impossible for an automated script to do. You might require a challenge be solved once an hour, say.
Use standard filtering techniques, like blocking certain IP addresses and refusing requests if they arrive too frequently.
Use obfuscation and encryption. This idea is based on a tricky little anti-spam plugin for Wordpress, HashCash (http://wp-plugins.net/plugin/wp-hashcash/). By outputting a customized piece of obfuscated JavaScript that's used to decrypt web service content, you force any client programmer to do two things: first, hook into a JavaScript engine in order to execute the code; second, consume resources performing the decryption. Neither is impossible, but they do make the task less appealing. Unfortunately, they also break the clean nature of web services, though you should be able to abstract the messy details with a suitable JavaScript API.

6.1.6. Real-World Examples

Just about any Ajax App has some kind of web service. In these examples, we'll look at a public API designed for third-party usage, then at a couple of services accessed only from a corresponding Ajax browser script.

6.1.6.1. Technorati API

Technorati (http://technorati.com) exposes its search capability for third-party use. To perform a query, run an HTTP GET on the following URL: http://api.technorati.com/search?key=1234&query=serendipity, where "1234" is your personal technorati key and "serendipity" is the search query. You'll get an XML document that lists the results.

6.1.6.2. NetVibes

NetVibes (http://netvibes.com) is an Ajax portal that gets it content from several web services. To get weather data, the browser invokes a service like this:

   http://netvibes.com/xmlProxy.php?url=http%3A//xoap.weather.com/weather/local/        USNY0996%3Fcc%3D*%26unit%3Dd%26dayf%3D4

The service is actually a proxy because it passes through to a real weather service at weather.com. As the URL shows, you can specify parameters such as location (USDNYC0996), units (d), and number of days ahead (4). The output is an XML document without any HTML markup:

   <weather ver="2.0">     <head>       <locale>en_US</locale>       <form>MEDIUM</form>       ...     </head>     <dayf>       ...       <hi>N/A</hi>       <low>46</low>       <sunr>7:18 AM</sunr>       <suns>4:34 PM</suns>       ...     </dayf>     ...   </weather>

6.1.6.3. Wish-O-Matic

Alexander Kirk's Wish-O-Matic (http://wish-o-matic.com) provides Amazon recommendations. The browser posts the following information to a service at http://alexander.kirk.at/wish-o-matic/search=grand&catalog=Books&page=1&locale=US&_=. The service then responds with a list of books. Unlike the previous service, the data is pure HTML, ready for immediate display in the browser.

   search=grand&catalog=Books&page=1&locale=US&_=   <table><tr><td style="width: 500px">       <b>Author:</b> Kevin Roderick<br/><b>Title:</b> Wilshire Boulevard:       The Grand Concourse of Los Angeles<br/><b>ISBN:</b> 1883318556<br/><a       href="javascript:void(add_item('1883318556', 'Wilshire Boulevard: The Grand            Concourse of Los Angeles',       'http://images.amazon.com/images/P/1883318556.01._SCTHUMBZZZ_.jpg'))">My       friend likes this item!</a></td>       ...       </td></tr>       </table>       <br/>       <a href="javascript:void(prev_page( ))">&lt; prev</a> |       <a href="javascript:void(next_page( ))">next &gt;</a>

6.1.7. Code Example: AjaxPatterns testAjaxCaller

AjaxCaller is a JavaScript HTTP client used in examples throughout this book (explained later in this chapter in "Code Example: AjaxPatterns TestAjaxCaller" for XMLHttpRequest Call). Here, we'll look at a web service used in the testAjaxCaller application (http://ajaxlocal/run/testAjaxCaller/), a very simple service that just echoes its input.

httpLogger begins by outputting a request method (e.g., "GET" or "POST"), its own request URL, and CGI variables present in the URL and body:

   echo "<p>Request Method: $requestMethod</p>";   echo "<p>Request URL: ".$_SERVER['REQUEST_URI']."</p>";   echo "<p>Vars in URL: ".print_r($_GET, TRUE)."</p>";   echo "<p>Vars in Body: ".print_r($_POST, TRUE)."</p>";

A separate function is used to read the body, which can also be outputted with a regular print or echo statement:

   function readBody( ) {     $body="";     $putdata = fopen("php://input", "r");     while ($block = fread($putdata, 1024)) {       $body = $body.$block;     }     fclose($putdata);     return $body;   }

6.1.8. Related Patterns

6.1.8.1. Web Services patterns

All the patterns in Web Services (Chapter 9) explain various strategies for designing Web Services with clean, maintainable interfaces.

6.1.8.2. Web Remoting patterns

The remaining Web Remoting patterns explain how the browser invokes a server-side Web Service.

6.1.8.3. Cross-Domain Proxy

The main point of this pattern is to guide on designing your own Web Services pattern. However, there are times when your server script will need to call on an external web service, as explained in Cross-Domain Proxy (Chapter 10).

6.1.8.4. Simulation Service

A Simulation Service (Chapter 19) is a "dummy" service that produces canned responses, a useful device while developing the browser-side of an Ajax App.

6.1.8.5. Service Test

The nice thing about web services, compared to most aspects of web development, is that it's easy to write automated tests, as described in Service Test (Chapter 19).