Views
The Human Face of Web Services
From PicoForms
Contents |
[edit] Introduction
The concept of a service delivered over the Web means different things depending on your point-of-view. To most of us a Web service probably means something like a Web site that allows you to find information, or to buy products. So we might use a weather forecast service, or a book purchasing service.
The business that runs such a site is likely to think of the functionality of the site as a set of more fine grained services. Each of these has to be thought about and managed individually, even though they are clearly related. So there might be a customer registration service, a purchase service, an order tracking service, and so on.
To the application developer a Web Service is a machine to machine data exchange over the Web. Machine Y asks a question of machine X, machine X answers. Each of the business services identified above might consist of a set of several of these lower level Web services, some of which the end user may never even be aware of. Indeed, automated processes may invoke Web Services that no human user will ever need to see.
However, the key thing to remember is that Web Services are used to drive applications used by human beings. So, the ability to quickly and easily integrate Web services into Web applications is really, most useful.
This article explores, at a fairly simple level, just how wonderful XForms, and so by association PicoForms' products, are as a front-end to Web services.
[edit] What is a Web Service Really?
To the developer the term "Web service" means one of two things:
- SOAP-based Web Services
- An exchange of XML documents between applications that follows the rather complex rules set out in various specifications that are mostly maintained by the W3C.
- RESTful Web Services
- REST (Representational State Transfer) is a formal description of how the Web is supposed to work. A Web browser asks for a representation of a resource (a Web page) to be transferred to itself for display. It identifies the resource by its unique name and address; its URL.
For our purposes it is enough to know that a Web service normally involves the transfer of XML documents between two applications for some well defined end. A Web service can be side-effect free, if it is simply a request and supply of information. On the other hand, a Web service can result in the change of state in an application, such as when an order is placed for goods.
We will concentrate our attentions on this lowest level of Web service, as it is the building blocks from which useful Web applications are built. If we can handle them, then all is well.
Our initial examination will concentrate on the side effect free variety, largely because they are more convenient to experiment with - there is no danger of accidentally spending money, or breaking something. Anyway, the mechanisms used to interact with Web services are the same whether or not they are side-effect free.
[edit] Two Examples
Luckily XForms handles both kinds of Web service.
[edit] A SOAP-based Web Service
SOAP is a technology that is by-and-large hidden from us application developers. We are taught to think that SOAP is far too complicated for us common folk. Instead we are sold nice, and often expensive, code-generation tools that hide the complexity under the lid of a comforting user interface.
Actually, as long as the XML content of SOAP-based Web services are well designed they are not really so bad to get to grips with, as the following example hopefully demonstrates.
[edit] flickr Web Services
A set of freely usable SOAP-based Web services is maintained by flickr to allow third parties to build applications that people can use to search for and retrieve photographs, as well as maintain their own photograph collections. Whilst the end-user is not likely to be directly aware of all the Web services being used to make a flickr application work (such as services used to authenticate the application itself), their combined effect is to produce applications that are largely user-centred.
The most immediately rewarding service to invoke is the search service. So here is the XML instance we need to send to flickr to tell it to do a search for us:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<s:Body>
<x:FlickrRequest xmlns:x="urn:flickr" xmlns="">
<method>flickr.photos.search</method>
<api_key>11111111111111111111</api_key>
<format>soap2</format>
<tags></tags>
<min_taken_date/>
<max_taken_date/>
<tag_mode>any</tag_mode>
<per_page>20</per_page>
<page>1</page>
</x:FlickrRequest>
</s:Body>
</s:Envelope>
It looks ghastly, but it isn't really so bad to work with as the complicated looking bits at the top can by-and-large be ignored. To carry out a search for a simple search term all we need to do is place the term to look for into the <tags/> element.
This we achieve with one XForm control, thus:
<xf:input ref="tags"> <xf:label>Search Terms (comma delimited):</xf:label> </xf:input>
Next we need to define the XForms submission to manage the calling of flickr's Web service with our search term. The submission must follow the rules of SOAP (just how silly does that sound?) and looks like this:
<xf:submission
id="subSOAP"
action="http://api.flickr.com/services/soap/"
ref="instance('instGetPhotos')"
method="post"
mediatype="application/soap+xml"
replace="instance"
instance="instResponse"
>
action is the address of the Web service we wish to use.
ref is the name of the XML document we wish to send to the Web service.
method and mediatype deal with the mechanics of the exchange of data with the Web service.
replace is set to instance, so that the search result is put into and XML document in the form.
instance is the name of the XML document that will contain the search result when it is returned.
The only things left to do are define the XML instance that will hold the search result, and then to do something with it in the UI so that the user can see what the search has turned up. Having done that, we will probably end up with something that looks rather like this:
Clearly we have cheated a bit, and populated more of the search definition XML document. However, the most important thing to note is that we are using the returned data to display thumbnail images that matched the search criteria, along with other information about the currently selected image.
With XForms, this is really simple to do. For example, here is the code that displays the title, description and date of the selected photo:
<p>
<xf:output value="fli:title">
<xf:label class="bold">Title: </xf:label>
</xf:output>
<xf:output value="fli:description">
<xf:label class="bold">Description: </xf:label>
</xf:output>
<xf:output value="fli:dates/@taken">
<xf:label class="bold">Date: </xf:label>
</xf:output>
</p>
Each output element binds directly to part of the XML document returned by the Flickr Web service, so there is really very little work to do in presenting this information to the user.
Title, description and date are simple to add to the UI, there is only ever one of them to display at a time. However, here can be many image tags, an there are usually a number of images anyway. Fortunately, the display of repeating items is very simple with XForms:
<xf:repeat nodeset="fli:tags/fli:tag" id="rptTag"> <xf:output value="."/> </xf:repeat>
Using the repeat element we specify the part of the XML document which may be present more than once, and then we output the content of that repeating element as many times as it occurs.
Every time we run a new search the result XML document is renewed and the UI refreshes itself to display the current result set.
In the real form, the tags themselves are active, so that when the user clicks on one, it is submitted as the search term in the Web service call, and a new result set is returned.
Similarly the paging buttons call the same Web service yet again, but each time specifying the previous or following result page to the one currently displayed. XForms' close relationship with XML resources, and the ability to work with Web services in a relatively simple fashion makes the construction of such an application really quite straightforward.
[edit] A 'RESTful' Web Service
It is not that easy to find an example of a truly RESTFul Web service. Many that claim to rest don't. It is common for "Restful" services simply to have a single URL providing many services. Parameters are passed to the URL, specifying the service required, and some XML is returned.
For example Amazon hosts a set of services from the one URL. The user distinguishes between services by passing the parameter Operation with the name of the desired service. For Example, to carry out a product search one calls the ItemSearch service:
Operation=ItemSearch
A service that followed RESTful principles more properly would have a different URL for each service. However, this hybrid style of service is widely used, so we will use the Amazon service as our example.
From the developer's view point it makes not a huge amount of difference whether a Web service is SOAPy or RESTful.
[edit] Amazon E-Commerce Service
This is a set of free-to-use services designed to help third parties to pass more business along to Amazon.
Just like flickr, Amazon has a service that lets you construct a search. Rather than passing the service an XML document that tells it what to do, we have to pass a set of name-value pairs appended to the URL of the service, like this:
http://ecs.amazonaws.co.uk/onca/xml? Service=AWSECommerceService &AWSAccessKeyId=12345 &Operation=ItemSearch &Composer=Byrd &ItemPage=1 &SearchIndex=Classical &ResponseGroup=Medium &Sort=titlerank
I have added line breaks to improve legibility. In this case we are searching for a composer by the name of Byrd in the Classical music part of the catalogue. We want the reponse to be of medium length (i.e. a bit more than the basic information) and the results to be sorted by title.
So, can an XForms processor build such a string and stick it on the end of a URL? Why certainly.
Just as with the flickr example, we bind a whole load of XForms input controls to an XML instance. This time the elements in the instance take the name part of the name-value pair we want to attach to the URL of the Web service. Like this:
<xf:instance id="instSearch" xmlns="">
<document>
<Service>AWSECommerceService</Service>
<AWSAccessKeyId>12345</AWSAccessKeyId>
<Operation>ItemSearch</Operation>
<Composer>Byrd</Composer>
<ItemPage>1</ItemPage>
<SearchIndex>Classical</SearchIndex>
<ResponseGroup>Medium</ResponseGroup>
<Sort>titlerank</Sort>
</document>
</xf:instance>
<xf:input ref="Composer" class="input"> <xf:label class="inputLabel">Composer: </xf:label> </xf:input>
The major difference comes in the XForms submission we need to define. With flickr we used method="post" to submit XML. With Amazon we change to method="get". The XForms processor now knows to construct name-value pairs from the XML instance referenced by the submission, and that is pretty much it.
The Amazon service returns XML, just like the flickr service, so we bind the incoming XML to an instance defined in the form, and once again we are ready to display information to the user, perhaps with something like this:
[edit] Conclusions
Clearly XForms is already an excellent choice Web application driven by interaction with Web Services, whether SOAP based or pseudo-RESTFul. This is largely thanks to XForms excellent support for XML data sources and the simple way submission of data is handled.
As always, the fact that the XForms model acts as an in-memory store for XML instances, makes life relatively simple for the developer. Being able to bind the UI to XML documents which can be updated internally, by user interaction with the form; or externally by interaction with Web services makes XForms a compelling platform.
