Designing Commercial Web Services: Part II

asp:feature

LANGUAGES: VB

TECHNOLOGIES: WebServices | WSDL | UDDI | Versioning

DesigningCommercial Web Services: Part II

Versioningand Client Support with the .NET Framework

By Dan Haught

With thebuzz about Web Services everywhere you go, you may be looking into this new wayof writing and making your software available. The concept of providingsoftware as a service is exciting, and Visual Studio .NET makes it easy tocreate the plumbing for Web Services based on Simple Object Access Protocol (SOAP)and XML. In PartI we started to look at the issues involved in creating a commercial WebService. With commercial Web Services, you make your service available to theoutside world, and that makes for a lot of additional design and implementationwork. In this installment, we will finish the two-part series on Web Servicedesign issues with coverage of versioning; Web Services Description Language(WSDL); Universal Description, Discovery and Integration (UDDI); working withWeb Service brokers; and providing the best level of client support.

Versioning

Planningfor versioning is a key aspect of Web Service design. Versioning deals with howyou handle new versions of your service. When you add new functionality, how doyou ensure you don t break compatibility? When it comes to versioning, even.NET s sparkling new SOAP- and XML-based Web Services model suffers from thesame painful versioning problems as any COM component. In the old days ofdeploying software to desktops through setup programs, installing an oldercomponent or overwriting shared components pretty much guaranteed your productwould affect your customer s computer adversely. With Web Services, you face asimilar problem: If you change the public interface for your Web Service on apublic server, you have the potential for service interruptions and veryunhappy customers.

So youmust think of versioning for Web Services as a contract with your customers.Your published interface needs to be every bit as binding as any legal documentyou sign. The following guidelines show the things you should and shouldn t do:

WSDL Formalizes Your Contract

Eventhough the Web Services infrastructure is in its infancy, there are varioustools you can use to ease versioning problems. The most important of thesetools is WSDL, which attempts to formalize XML syntax for describing a WebService s interface. Through WSDL, you define not only what your serviceprovides but also what a client must do in order to use the service. As such,WSDL is the first attempt at creating a standardized format for contractsbetween you and your service s clients.

As anexample, assume you have a Web Service that accepts the name of a city andreturns the current weather. While this is obviously a very simple interface,it serves well to show WSDL in action. The Visual Basic .NET code in FIGURE 1shows the basic code to implement the service.

Public Function GetWeather( _

  ByVal City As String) As String

  Select Case City

    Case "Washington, D.C."

      Return "Hot and miserable."

    Case Else

      Return "Sorry, your city currentlyhas no weather."

  End Select

End Function

FIGURE 1:The GetWeather method.

Thismethod accepts a string and returns a string. When you generate the wsdl filefor your Web Service, you get a complete description of the interface. FIGURE 2contains a snippet from the example service s WSDL. From the WSDL, you can seethat one method named GetWeatheris exposed, it accepts a string named City,and it returns a string.

           elementFormDefault="qualified"        targetNamespace="http://tempuri.org/">                                                       name="City"nillable="true"                type="s:string" />                                                                                 maxOccurs="1"name="GetWeatherResult"               nillable="true"type="s:string" />                                           type="s:string" />         FIGURE 2:WSDL for GetWeather.   Additionaltext in the wsdl file describes how SOAP messages are formatted and describesnamespaces and Uniform Resource Identifiers (URIs) needed to access theservice. Later in this article, you ll see how WSDL works in concert with otherstandards, such as disco files and UDDI, to allow others to discover yourservice. For now, remember that WSDL describes your public interface incomplete detail.   Parallel Service Deployment AlthoughWSDL provides a roadmap for both your Web Service and the clients who consumeit, no provisions specifically address the versioning problem. Additionally,the .NET Framework itself deals with versioning through powerful new standardsthat allow for multi-version global and local assemblies with self-describingmanifests to offer guaranteed backward compatibility. While this certainlyhelps you version and deploy the internal components on your server, it offersno help in terms of the interfaces your Web Service exposes to clients.   If yourWeb Service will never change, add new features, or expand in response tocustomer requests, then you re fine and have no need to worry about versioning.But, in the real world, you have to plan for changes in your services. So,without direct help from WSDL, the .NET Framework, or other standards currentlydefined, you need to create a versioning plan for your service that isextensible and also guarantees backward compatibility.   Fortunately,there is a workable solution to the versioning problem. When you make a requestof a Web Service, you are using SOAP (specifically the SOAPAction call) to makecalls to the server. SOAPAction is where you specify the URI. The URI containsnot only the address of the service, but information about the call to make.This flexible addressing scheme, combined with .NET s ability to run any numberof Web Services concurrently, gives you what you need to solve the versioningproblem: parallel service deployment.   In thisdesign, you implement new versions of your service as additional Web Serviceson your server. Existing versions are still available, and other versions havenot changed their interfaces and functionality. (Remember your contract withthe customer?) Clients access new functionality by referring to a different URIto access newer versions of your service. Of course, in order to consume yournew service, your customer has to rewrite his or her client code to match yournew interface. But, with parallel services, your customer can choose when tomake the switch. Additionally, parallel deployment allows you to maximizerevenues by charging different prices for different versions. Likely, you willhave customers who are completely happy with version 1. But those asking forversion 2 will be willing, no doubt, to pay a premium if your new functionalityis compelling enough. FIGURE 3 shows the basic design of parallel versioning,with different clients accessing specific versions directly by URI, or throughdiscovery.  
FIGURE 3: Parallel servicedeployment.   Versioninghappens not only when new features are required, but also when you need to fixbugs in your service. Up-front testing could limit your exposure to softwaredefects, but you should plan for bug fixes. When updating versions to fix bugs,you generally don t have to change your public interface. For example, if yourservice returns the integer result of adding two numbers together, and yourmath is wrong, your new version still will accept two integers and return twointegers, but with internal changes. Of course, if the bug cannot be fixedwithout an interface change, then something went very wrong during your designphase and can only be fixed by creating a new version.   The keyto successful bug-fix versioning is regression testing. You must be sure totest all the inputs and outputs of your service in both the before and afterversions to ensure you haven t changed your contract. When doing this, you willfind WSDL truly useful. Use Microsoft s WSDL.EXE tool (included with the .NETFramework) to generate WSDL documents for both versions and compare the two.Any inadvertent changes in your interface will become readily apparent.   Client Support Thereare several models for consuming Web Services. With the first, you supply not onlythe Web Service, but also the client-side software. In this scenario, you dothe work of designing, building, and testing the client software that initiatesWeb Service requests and works with the returned data. When you are writing theclient software, your support duties follow those of traditional software. Youprovide a setup program, documentation on how to run your program, andtechnical support for the end user.   Thesecond client model for Web Services is one in which the client is responsible forwriting logic to access your Web Service. This model requires more planningbecause the level of effort required to support these clients is greater. Ifyour commercial Web Service expects your customers will need to implement theirown front end, how do you provide them with the best possible client support?After all, if you can t provide your customers with the tools and resourcesthey need to consume your Web Service, you won t have very many customers. Thefirst step using this model is to decide which client platforms you plan tosupport. Obviously, if you are authoring your Web Service using the .NETFramework, the ideal candidate for client development is Visual Studio .NET,which makes creating Web clients a snap. Visual Studio .NET generates all theproxy code to bind a service s interface to classes you can use in codedirectly. There is no need to write WSDL discovery code explicitly, or to writebinding code to match Web Service output to client code.   Theprospect of cross-platform client support is more difficult. If you plan tosupport non-.NET clients, you need to plan for testing to ensure your service(and especially its documented interface) work on the platforms you support.Because Web Services are in their infancy, there are many unresolved issueswith compatibility across platforms. Will a Java client be able to workeffectively with your .NET-based Web Service? What are the minimum requirementsfor versions of HTTP, SOAP, and WSDL on your client s computers? Obviously,sticking to a pure .NET client means simpler testing, documentation, andsupport. But your business model may dictate that you support other platforms.At a minimum, consider supporting clients who are using Microsoft developmenttechnologies but are not yet in the .NET world. You can do this by providingsupport for the Microsoft SOAP toolkit, which allows you to implement WebService clients in current COM-based environments like ASP, VB, and VC++.   Once youdecide on your client plan, you need to map out the pieces that ensure the bestpossible experience for your customers. The starting point is a well-documentedinterface. You need extensive documentation about the methods your Web Serviceexposes, including detailed data on parameters, expected values, sequencing, andreturn values. Additionally, you need to provide a complete list of the errorcodes your service returns. If you have ever used third-party components inyour development work, you know the importance of rock-solid API documentation.   Next,you need to provide the customer with resources that will get his or her clientcode up and running as soon as possible. Remember, every day the customerspends building the system is a day when that client is not billable. The mostimportant resources for developers are sample projects. If you provide aworking sample project, complete with source code, notes, and a user interface,your customer can see quickly how your service is structured and how to callit. Sample projects should include code and notes that cover every method andcall that your Web Service exposes. Don t skimp on what you may consider lesserfeatures these may be the features your client really needs. And, withoutsamples and documentation, adoption will be slow. Also, be sure to includetroubleshooting tips covering as many possible scenarios as you can imagine.   Finally,depending on the pricing model of your Web Service, consider offering customclient implementation services. For a fixed or per-hour fee, you can provideyour customer with some or all of the authoring skills needed to implement asuccessful client in the least amount of time.   Additional Security Issues Beforefinishing your Web Service design, think about any security issues you did notexplicitly cover so far. One of the key aspects of Web Services security is thefact that data is sent back and forth as clear text XML. This is one of themost common perceived weaknesses in Web Service security, but you can handle itvery easily. At a minimum, your Web Service should be available through theSecure Sockets Layer (SSL). Configuring your server to handle SSL typicallyrequires the installation of one or more server certificates, and a few IISsettings. Beyond offering SSL access as an option, you should consider makingit a requirement. If any sensitive data (including authentication items) istransmitted, it is in your best interest to require access through SSL.Implementing this requires some work, but it basically involves checking theWeb Service request to ensure it comes through a URL prefaced with https: .Your server can implement logic that disallows access through non-SSLconnections and returns an error message.   Takingsecurity further, you can design your Web Service to require encryption of datastreams using strong encryption. The .NET Framework offers strong encryptionalgorithms, such as DES (Data Encryption Standard), DSA (DigitalSignature Algorithm), and MD5in the System.Security.Cryptography library. However, implementingadditional encryption involves designing and writing another layer on top ofyour Web Service that encrypts and decrypts XML data on the fly. You have todecide if this level of security is worth the development costs and the server-and client-processing overhead.   Oneinteresting security concept people often overlook are exploited errormessages. Using the authentication components discussed in last month sarticle, you must decide carefully what information to return in the case oferrors. Too much information could provide a hacker with just enough data tocompromise your security. Imagine a scenario in which an authentication attemptcomes into your server. If the account name or password is invalid, or theaccount has expired, your service returns an error message. What interests ahacker are the contents of that error message. For example, if you return amessage that states the account name and password are valid, but the account isexpired, the hacker now knows a valid login. A more secure scheme is to returnonly minimal information. Limited information gives valid clients an indicationthere is a problem they can resolve through legitimate channels, butunauthorized visitors get no additional help.   Going Public with UDDI, Disco Files, and Brokers Marketingis a key part of any business endeavor. Your commercial Web Service is only assuccessful as the number of clients using it. Beyond traditional software andservices marketing, you should be familiar with several developments in WebServices.   Thefirst is UDDI. This standard, backed by many of the major software and platformvendors, is a platform-independent set of technologies, integrated to provide amodel for describing services available on the Web. Think of UDDI as the YellowPages for companies that offer products or services on the Web. Although UDDI sbroad goal of unifying business service and product discovery encompasses muchmore than just Web Services, UDDI brings some important items to the table.First, Visual Studio .NET generates both the disco and wsdl files that UDDIuses. This means most of the work is done for you and allows client searches tofind and catalog the Web Services you offer. However, it also assumes theperson doing the search knows your URIs. In most cases, needing to know theURIs for Web Services defeats the purpose of doing searches in the first place.   So,several UDDI backers have created the UDDI Registry. The registry is asearchable database of resources that have been cataloged with UDDI. The goodnews is that registration is typically painless and free. For an example of theregistration process, try out the Microsoft UDDI Registry at http://uddi.microsoft.com/register.aspx.   Once aclient has made a UDDI search request, information returns from the UDDIRegistry or a Web Services broker that contains a link to a discovery file(disco files in the .NET world). They point to additional information about WebServices, such as the location of the wsdl files. Once the client has the linkto the discovery document for a Web Service, it can directly request thediscovery file.   Afterprocessing the discovery file, the client receives one or more files containingWSDL content. You ll remember the WSDL allows you to use a standardized XMLformat to describe your services and how to access them and is a key part ofthe discovery process. If all this seems a bit much to digest in one sitting,don t worry. Visual Studio .NET automatically generates the disco and wsdlfiles for Web Services you create. And often, that s more than half the work.   To seethis convoluted process in action, see FIGURE 4, a diagram of the typicaldiscovery process for Web Services.  
FIGURE 4: Web Servicediscovery.   It isimportant to note that UDDI and its registry are still in an early phase ofdevelopment. Not many potential service consumers know about UDDI, and searcheson the current entries are limited to overly broad classifications. So don tassume inclusion in the UDDI registry is your key to success. It is merely oneof many pieces in the marketing puzzle. As UDDI and Web Services mature, theregistry likely will become ubiquitous, but for now the onus is on you to getthe word out.   Anotherimportant trend in Web Services is the concept of Web Service brokers. Siteslike http://www.salcentral.com and http://www.xmethods.net are working toprovide the next generation of Web Service infrastructure. Web Service brokersprovide search engines that directly match your Web Service needs against averified database of known providers. Brokers add additional value throughversion brokering, testing, and other services that benefit both the providersand consumers. As you get closer to going live with your commercial WebService, consider working with brokers to gain additional exposure for yourwork.   Conclusion Withouta doubt, Web Services offer intriguing new business and development challenges,as well as potential rewards. In this series of two articles, you have seenthat there are many design and technical issues to iron out before you startcoding your commercial Web Services. Your challenge now is to do the actualwork of mapping your business model to Web Service architecture. While planbefore you code may be a truism in the software industry, the complexities anduncharted territories that are Web Services make careful planning and design amust. Finally, don t feel constrained by the models presented here. The newnessof Web Services dictates nothing. As long as you plan, feel free to come upwith creative designs and models.   Dan Haught manages product development for FMS, Inc. inVienna, VA, where he is responsible for shipping developer products for VisualBasic, SQL Server, Access, and (soon) .NET. He frequently speaks at developerconferences and has written several books and many articles on currentdevelopment topics. Readers may contact him at mailto:[email protected].  Tell us what you think! Please send any comments about thisarticle to [email protected] include the article title and author.