742 Chapter 31 Connecting to Web Services with XML and SOAP <BrowseNode> <BrowseName>Computer Networks</BrowseName> </BrowseNode> <BrowseNode> <BrowseName>Computer Bks - Languages / Programming</BrowseName> </BrowseNode> <BrowseNode> <BrowseName>Computers</BrowseName> </BrowseNode> <BrowseNode> <BrowseName>Programming Languages - General</BrowseName> </BrowseNode> <BrowseNode> <BrowseName>Internet - Web Site Design</BrowseName> </BrowseNode> <BrowseNode> <BrowseName>Database Management - SQL Server</BrowseName> </BrowseNode> <BrowseNode> <BrowseName>Programming Languages - SQL</BrowseName> </BrowseNode> </BrowseList> <Media>Paperback</Media> <NumMedia>1</NumMedia> <Isbn>0672317842</Isbn> <Availability>Usually ships within 24 hours</Availability> <SimilarProducts> <Product>0735709211</Product> <Product>1861003730</Product> <Product>073570970X</Product> <Product>1861006918</Product> <Product>0596000413</Product> </SimilarProducts> </Details> </ProductInfo> The document begins with the following line: <?xml version="1.0" encoding="UTF-8"?> This is a standard declaration that tells us the following document will be XML using UTF-8 character encoding. Look at the body of the document.The whole document consists of pairs of opening and closing tags, such as <ProductName>PHP and MySQL Web Development</ProductName> Listing 31.1 Continued 37 525x ch31 1/24/03 3:35 PM Page 742 743 Understanding XML ProductName is an element, just as it would be in HTML. And, just as in HTML, we can nest elements: <Authors> <Author>Luke Welling</Author> <Author>Laura Thomson</Author> </Authors> Also like HTML, elements can have attributes. For example: <Details url="http://www.amazon.com/exec/obidos/redirect?tag= tangledwebdesign%26creative=XXXXXXXXXXXXXX%26camp=2025%26link_code =xm2%26path=ASIN/0672317842"> This Details element has a single attribute url. There are also some differences from HTML.The first is that all opening tags should have a closing tag. (The exception to this is that you may have a single tag if you use a special format. If you are familiar with XHTML, you will have seen the <br /> tag used in place of <br> for this exact reason.) In addition, all elements must be properly nested. The main difference you will have noticed between XML and HTML is that we seem to be making up our own tags as we go along! This is the flexibility of XML.We can structure our documents to match the data that we want to store.We can formalize the structure of XML documents by writing either a DTD (Document Type Definition) or an XML Schema. Both of these documents are used to describe the structure of a given XML document. If you like, the DTD or Schema is like a class declaration, and the XML document is like an instance of that class. You can read Amazon’s DTD for this document here: http://xml.amazon.com/schemas2/dev-heavy.dtd You can read the XML Schema for it here: http://xml.amazon.com/schemas2/dev-heavy.xsd You will not be able to open the DTD file in some browsers, because they will try to parse the DTD as XML and get confused.You can, however, download it and read it in the editor of your choice.You should be able to open the XML Schema directly in your browser. You will notice that, other than the initial XML declaration, the entire body of the document is contained inside the ProductInfo element.This is called the root element of the document. Let’s take a closer look: <ProductInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xml.amazon.com/schemas2/ dev-heavy.xsd"> You will see that it has some slightly unusual attributes.These are XML Namespaces.We do not need to understand namespaces for what we want to do in this project, but they 37 525x ch31 1/24/03 3:35 PM Page 743 744 Chapter 31 Connecting to Web Services with XML and SOAP can be very useful.The basic idea is to qualify element and attribute names with a name- space so that common names will not clash when dealing with documents from different sources. If you’d like to know more about namespaces, you can read the document “Namespaces in XML Recommendation” at http://www.w3.org/TR/ REC-xml-names/. If you would like to know more about XML in general, there is a huge variety of resources.The W3C site is an excellent place to start, and there are also literally hundreds of excellent books and Web tutorials. ZVON.org is one of the best Web-based ones. Understanding Web Services We b services are application interfaces made available via the World Wide Web. If you like, a Web service can be seen as a class that exposes its public methods via the Web. Web Services are now becoming wide-spread, and some of the biggest names in the business are making some of their functionality available via Web Services. For example, Google now offers a range of Web Services. After you have gone through the process of setting up a client to the Amazon interface in this chapter, you should find it very straightforward to build a client interface to Google.You can find more information at http://www.google.com/apis/. An ever-growing list of public Web Services is available at http://www.xmethods.net. There are a number of core protocols involved in this remote function call methodol- ogy. Tw o of the most important ones are SOAP and WSDL. SOAP SOAP is a request-and-response-driven messaging protocol that allows clients to invoke Web Services and allows servers to respond. Each SOAP message, whether a request or response, is a simple XML document.A sample SOAP request we might send to Amazon is shown in Listing 31.2. Listing 31.2 SOAP Request for a Search Based on the ASIN <?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <SOAP-ENV:Body> <namesp1:AsinSearchRequest xmlns:namesp1="urn:PI/DevCentral/SoapService"> 37 525x ch31 1/24/03 3:35 PM Page 744 745 Understanding Web Services <AsinSearchRequest xsi:type="m:AsinRequest"> <asin >0060518057</asin> <tag >your-associate-id</tag> <type >heavy</type> <dev-tag >your-dev-tag</dev-tag> </AsinSearchRequest> </namesp1:AsinSearchRequest> </SOAP-ENV:Body> </SOAP-ENV:Envelope> The SOAP message begins with the declaration that this is an XML document.The root element of all SOAP messages is the SOAP envelope.Within this we find the Body ele- ment that contains the actual request. This request is an AsinSearchRequest, which asks the Amazon server to look up a particular item in its database based on the ASIN, which stands for Amazon.com Standard Item Number.This is a unique identifier given to every product in the Amazon.com database. Think of the AsinSearchRequest as a function call on a remote machine, and the elements contained within this element as the parameters we are passing to that func- tion. In this case, we are passing an ASIN for the Dilbert book Way of the Weasel.We also need to pass in the tag, which is your Associate ID; the type of search to perform (heavy or lite); and the dev-tag, which is a developer token value Amazon will give you.The element type tells the service whether we want limited detail (lite) or all available information (heavy). The response to this request is very similar to the XML document we looked at in Listing 31.1, but enclosed in a SOAP envelope. When dealing with SOAP, you will usually generate SOAP requests and interpret responses programmatically using a SOAP library, regardless of the programming lan- guage you are using.This is a good thing as it saves on the effort of having to build the SOAP request and interpret the response manually. WSDL WSDL stands for Web Services Description Language. (It is often pronounced “wiz-dul.”) This is used to describe the interface to available services at a particular Web site. If you would like to see the WSDL document describing the Amazon Web Services we will use in this chapter, it is located at http://soap.amazon.com/schemas2/ AmazonWebServices.wsdl. As you will see if you follow this link,WSDL documents are significantly more com- plex than SOAP messages.You would always generate and interpret them programmati- cally, if given a choice. If you would like to know more about WSDL, you can consult the W3C Draft at http://www.w3.org/TR/2002/WD-wsdl12-20020709/. Listing 31.2 Continued 37 525x ch31 1/24/03 3:35 PM Page 745 746 Chapter 31 Connecting to Web Services with XML and SOAP At the time of writing,WSDL was not yet a W3C Recommendation so it is still subject to change.This has not stopped developers everywhere from using it enthusiastically. However, like all pieces of the Web Services puzzle, it is subject to change as the whole area is so new. Solution Components There are a few parts we will need to build our solution. Building a Shopping Cart We will obviously need to build a shopping cart as the front end for the system.We’ve done this before, in Chapter 25,“Building a Shopping Cart.” Because shopping carts are not the main focus in this project, we will use a simplified application.We just need to provide a basic cart so that we can track what the customer would like to buy and report it to Amazon upon checkout. Using Amazon’s Web Services Interfaces To use the Amazon Web Services interface, you will need to download the Amazon Web Services Developers’ Kit.We got it from http://associates.amazon.com/exec/ panama/associates/join/developer/kit.html.This URL is probably subject to change, however. You will also need to sign up for a Developer Token.You can do this at the same site. This token is used to identify you to Amazon when your requests come in. You might also like to sign up for an Amazon Associate ID.This will enable you to collect commission if people buy any products via your interface. When you download the developer kit, read through it. It comes with documentation on how the interface works, and code samples in a variety of languages, including PHP. Before you can download it, you need to agree to the license agreement.This is worth reading, as it is not the usual yada-yada software license. Some of the license conditions that are important during implementation are the fol- lowing: n You must not make more than one request per second. n You must cache data coming from Amazon. n You must not cache prices for more than one hour. n You must not cache other data for more than 24 hours. n You must link every piece of Amazon data back to a page on Amazon.com. With a hard-to-spell domain name, no promotion, and no obvious reason to use Tahuayo.com instead of going straight to Amazon.com, we do not need to take any fur- ther steps to keep requests below one per second. 37 525x ch31 1/24/03 3:35 PM Page 746 . books and Web tutorials. ZVON.org is one of the best Web- based ones. Understanding Web Services We b services are application interfaces made available via the World Wide Web. If you like, a Web. pairs of opening and closing tags, such as <ProductName> ;PHP and MySQL Web Development& lt;/ProductName> Listing 31.1 Continued 37 525x ch31 1/24/03 3:35 PM Page 742 743 Understanding XML ProductName. o of the most important ones are SOAP and WSDL. SOAP SOAP is a request -and- response-driven messaging protocol that allows clients to invoke Web Services and allows servers to respond. Each SOAP