Chapter 16: Web Services

What do Amazon, Google, and Microsoft MapPoint, among many other sites and products have in common with each other? And is there anything out there that would allow you to leverage their functionality in your own websites? Well, yes there is – web services, of course! Web services are the Internet's hot new technology that everyone is talking about. However, few people really understand what they are or how to use them correctly. In this chapter of the book, we'll look at just what a web service is, what encompasses the overall vision for web services, and how to create and leverage existing web services effectively.

What is a Web Service?

Let's begin with the question, what are web services? At a high level, the technology is much simpler than might seem possible considering how much hype there is regarding their power and the possibility of their changing the entire face of the Web. Web services enable two different applications, no matter whether they are within the same building or on opposite sides of the planet, to talk to each other. They can do this through using a common language and syntax.

Prior to web services, (for those of you who are thirsty for a bit of history!), there had been other attempts to provide a way for different, or distant systems to communicate with each other. Among these were technologies called Distributed COM, or DCOM, and CORBA, and others were tried, too. However, none of these attempts ever gained critical acceptance or implementation in the industry. They were too complicated to set up, and the various technologies couldn't work together.

Then, along came web services, which allowed applications to happily talk to each other, wherever they were. The biggest problem with web services for our purposes, though, is the heap of acronyms and buzzwords that go along with them. In this chapter, we'll be exploring things called XML, HTTP, SOAP, and WSDL. These are all important to web services so we're going to make sure that you gain a full understanding of them, putting some meaning behind the letters!

The best way to learn about the stuff that makes web services work is to build one ourselves. We're going to create a page from which we can allow the fans to search for music on Amazon's site. We'll give them a textbox to enter a keyword to search for, and then return some matching music. We'll display the artist's name, the name of the album, and Amazon's price.

Accessing Amazon's Web Services

Amazon has a Web Services Developer's Kit that you can download to get documentation and samples for their web services. To find this, type in the following URL http://associates.amazon.com/exec/panama/associates/join/developer/kit.html. It is worth reading the documentation as it'll be important when you need to know the values that are valid when you're using web services. We'll go through just a small subset of the full functionality provided by Amazon, but for if you want to know some more, keep reading through that documentation!

OK, so now we need to download our developer's kit. Amazon states that you will need to get a developer's token before you can use their web services, and the URL above will give you a link to requesting one. This token is your unique identifier as you access Amazon's services. You will pass it every time you access any Amazon web service. Fortunately, it's free, so go ahead and get one – you'll need it to try out the examples.

Generate the Proxy Class

The first thing we need to do is create something called a proxy class through which we can access Amazon's web services. In general terms, a proxy is something that acts as an intermediary between one item for another. For instance, if you can't vote, you could get someone to vote for you. That person would then be your proxy, acting on your behalf. For our web service, we need something to act as a proxy between our application and the web service. Using this will mean that we don't need to understand the complexities of the web service.

Web Matrix makes this really quite easy to do. Most websites that provide web services have a document available, called a WSDL (Web Service Description Language) document, which describes the methods, properties, and other behavior provided by the web service. Web Matrix has a tool called the XML Web Service Proxy Generator that takes this WSDL document and creates a class that acts as a proxy for the web service.

Try It Out—Creating a Proxy Class for Amazon's Web Service

In Web Matrix, choose Tools | WebService Proxy Generator from the toolbar at the top, and you will be presented with the XML Web Service Proxy Generator dialog. This dialog has a number of textboxes, which you need to fill in to match the following:

Hit the Generate button and that's it! Your proxy class with all of the code necessary to talk to the Amazon web service is generated and placed in the location you specified.

How It Works

The Web Matrix proxy generator does a lot of work behind the scenes. It reads the WSDL document, which it locates from the URL we give it in the dialog box above (http://soap.amazon.com/schemas2/AmazonWebServices.wsdl). It then actually creates the methods you'll need to access the available web service functionality.

The screenshot that follows is of the first portion of Amazon's WSDL document. If you'd like to view this for yourself, you just need to point your browser at the URL we gave to the proxy generator:

This document describes everything the proxy generator needs to know to access the services. The language it is written in is XML, which is a markup language, like the HTML that we have seen already in our applications. What makes it so useful to web services, however, is that it provides strict rules to everybody who uses it on what they can write and how it should be written. This standardizes what is sent and received to a format that everything can understand.

While a proxy class means that you don't need to actually go in and view the WSDL directly, it's good to get in and have a look at what is going on.

The proxy generator takes this information and creates a Visual Basic .NET file, called Amazon.vb, which contains methods and classes you can use. It also goes one step further if we tell it to do so, and compiles this class for us into a DLL. It places this DLL into the bin directory under the output directory we specified, in a similar way to that whichwe have seen in previous chapters when compiling class libraries. In our example, it created a DLL called Amazon.dll under C:\BegWebMatrix\Ch16\bin. There are many classes and methods created, but we're only interested in three of them.

Let's take a look at Amazon.vb. There is a lot in here, and a great deal of it is information for formatting the requests sent to and from the web service. (This is taken care of by a technology called SOAP, or the Simple Object Access Protocol. It works by providing a standard syntax for the data being sent back and forth to ensure that both our application and the web service understand one another. If you'd like more information on SOAP, take a look at http://www.w3.org/2000/xp/Group/).

We don't need to worry about this as we want to look at the methods themselves. What I've done is take the code in Amazon.vb and strip it of the extra detail. This is only to clarify what's in the file, so DON'T do this with real code!!

What you have is a class called AmazonSearchService in a namespace called Amazon:

Option Strict Off Option Explicit On Imports System Imports System.ComponentModel Imports System.Diagnostics Imports System.Web.Services Imports System.Web.Services.Protocols Imports System.Xml.Serialization Namespace Amazon   Public Class AmazonSearchService     Inherits System.Web.Services.Protocols.SoapHttpClientProtocol

It has a property that contains the URL that is used to interact with the web services. In this case, Amazon has placed the web services at http://soap.amazon.com/onca/soap2:

    Public Sub New()       MyBase.New       Me.Url = "http://soap.amazon.com/onca/soap2"     End Sub

The following is one of the many provided functions. This function, KeywordSearchRequest(), takes an object of type KeywordRequest as its parameter, and returns an object of type ProductInfo:

Public Function KeywordSearchRequest _   (<System.Xml.Serialization.SoapElementAttribute("KeywordSearchRequest")> _     ByVal KeywordSearchRequest1 As KeywordRequest) As _     <System.Xml.Serialization.SoapElementAttribute("return")> ProductInfo   Dim results() As Object = _     Me.Invoke("KeywordSearchRequest", New Object() {KeywordSearchRequest1})   Return CType(results(0),ProductInfo) End Function

We're going to need to use this method, and to do so, we need to know more about the KeywordRequest type and the ProductInfo type. They can both be found towards the end of the Amazon.vb file.

The KeywordRequest type is shown here, again stripped of excess detail that we don't need:

  Public Class KeywordRequest     Public keyword As String     Public page As String     Public mode As String     Public tag As String     Public type As String     Public devtag As String     Public sort As String   End Class 

Here's a rundown of the properties in the KeywordRequest class:

Property	Description
keyword	This is the keyword you are searching for.
page	Some searches could return a tremendous amount of results. Amazon limits each search to ten results per call. You pass the page of results you want returned with this property. If you want the first ten results, you pass a "1". For the second ten results, pass a "2", and so on.
mode	This is the area of Amazon you're searching. A couple of examples are "music" and "books".
tag	This is the associates tag. To be honest, I don't know the significance. I do know that you need to set it to "webservices-20".
type	This signifies the amount of detail returned. "lite" signifies that only essential information such as name, artist, and prices are returned. "heavy" signifies that additional information such as customer review data is returned.
devtag	This is your developer token.
sort	This is the way you want your results sorted. See the Amazon documentation for the possible values. We'll sort our items alphabetically, which is "+titlerank".

The return value we receive when we call KeywordSearchRequest is of type ProductInfo. Here's the stripped version:

  Public Class ProductInfo     Public TotalResults As String     Public ListName As String     Public Details() As Details   End Class

Here are the properties and their descriptions:

Property	Description
TotalResults	The total results available based on the search criteria.
ListName	Undocumented, but don't worry, we don't use this in our application!
Details()	This is an array of the results of type Details.

The Details type contains all pertinent information for each returned item. If you look in the generated class, you'll see that this type has many, many properties. I won't show you all of them, but here is a description of the ones we'll use:

Property	Description
URL	A link to the item on Amazon's site.
ProductName	The name of the item.
Artists()	A string array of all the involved artists.
OurPrice	Amazon's price for the item.

Create an Amazon Search Page

Now that we have a better understanding of the classes we'll utilize, let's create an example.

Try It Out—Searching Amazon.com

1. Create a new ASP.NET page and call it AmazonSearch.aspx. This page needs to be in the same folder as the one you generated your Amazon.vb file into.

2. Add the text Search Amazon for: and add a textbox with ID of txtSearch to the right of it.

3. Hit Return, then add a button and set its ID to btnSearch and the text to Search.

4. Finally, add a label control at the bottom of the page, with the ID of lblResults and clear its Text property. This is where we'll place the returned item list.

5. While still in design mode, double-click on the btnSearch button and add the following code in the click event handler:

   Sub btnSearch_Click(sender As Object, e As EventArgs)  Dim amazonsrch As New Amazon.AmazonSearchService()  Dim productinfo As Amazon.ProductInfo  Dim keyrequest As New Amazon.KeywordRequest()  Dim details As Amazon.Details  keyrequest.keyword = txtSearch.text  keyrequest.page = "1"  keyrequest.mode = "music"  keyrequest.tag = "webservices-20"  keyrequest.type = "lite"  keyrequest.devtag = "xxxxxxxxxxxxxx"  Try  productinfo = amazonsrch.KeywordSearchRequest(keyrequest)  If cint(productinfo.TotalResults) > 0 Then  lblResults.text = ""  For Each details In productinfo.Details  lblResults.text &= "<a href=""" & details.URL & """>"  If ubound(details.artists) >= 0 Then  lblResults.text &= details.artists(0) & " - "   End If  lblResults.text &= details.ProductName & " - " & _  details.OurPrice & "</a><br />"  Next  Else  lblResults.text = "No results found"  End If  Catch  lblResults.text = "There was an error with this search."  End Try End Sub

Now you can try the page out. You should be able to search for any music that has the text you specify as part of the author, title, or keywords. I've searched for Cornflakes below, but unfortunately, I guess our CD is too new to be listed yet! Here are the results of using the web service:

How It Works

Let's look at the code we inserted in the click event handler for our button.

First, we need an instance of the AmazonSearchService object. We name ours amazonsrch and this is the class in which the web service's methods are located:

  Dim amazonsrch As New Amazon.AmazonSearchService()

As we've discussed, the results are returned in an object called ProductInfo:

  Dim productinfo As Amazon.ProductInfo

The next object is what we pass to the web service to specify the properties of our search:

  Dim keyrequest As New Amazon.KeywordRequest()

The details of the search results are held in the following object:

    Dim details As Amazon.Details

Next we specify our search properties:

    keyrequest.keyword = txtSearch.text     keyrequest.page = "1"     keyrequest.mode = "music"     keyrequest.tag = "webservices-20"     keyrequest.type = "lite"     keyrequest.devtag = "xxxxxxxxxxxxxx"

The keyword is set to the value that the user types into the textbox on the page. We are only going to return the top 10 results, so we can just display page 1 of the results. The mode is set to music as that's what we're searching for. Next, we are only going to use the values we can get from the lite return results. Finally in the above code, we have to enter the token string in the devtag property. As I said earlier, you need to get your own token from the Amazon link. (At the time of writing, it was possible to carry out this example without actually using your developer's token but there is every chance that Amazon will start checking these so it's probably better to use it!)

We need to gracefully handle errors, especially when dealing with web services. Even if your code is perfect (which, of course it is!), you can't always count on the Internet being available, and then, even if it is, you can't count on the web service provider being available and bug-free.

So, we start off with a Try block declaration so that we can trap and deal with any errors. Then, we get the ProductInfo object after calling the KeywordSearchRequest() method. We pass our keyrequest object to the method so that the web service knows what to search for:

      productinfo = amsrch.KeywordSearchRequest(keyrequest)

We need to check to see if any results are returned. Since TotalResults is a string property, we need to convert it to an integer first:

      If cint(productinfo.TotalResults) > 0 Then

Next, we're saying that if we've got some results, let's clear lblResults, because we're going to add stuff into it:

        lblResults.text = ""

Then we run through all of the results details:

        For Each details In productinfo.Details

We're placing hyperlink HTML in lblResults. First, we set the a tag's href attribute to the returned URL. This URL is a link to the product details on Amazon's website:

          lblResults.text &= "<a href=""" & details.URL & """>"

If any artists are returned, they'll be displayed as the first part of the link text:

          If ubound(details.artists) >= 0 Then             lblResults.text &= details.artists(0) & " - "            End If

Finally, we show the product's name and Amazon's selling price, and then we close the a tag.

        lblResults.text &= details.ProductName & " - " & _            details.OurPrice & "</a><br />"

If the TotalResults is 0, we let the user know that there were no results, using the following line:

        lblResults.text = "No results found"

If there are any errors at any point, we handle them by letting the user know:

    Catch       lblResults.text = "There was an error with this search."     End Try