Introduction

Microsoft Corporation

August 2003

Summary: Building Interoperable Web Service: WS-I Basic Profile 1.0 is intended to help software architects and developers design and code Web services that are interoperable. We emphasize "interoperable" because we assume that you already understand how to implement a Web service. Our goal is to show you how to ensure that your Web service will work across multiple platforms and programming languages and with other Web services. Our philosophy is that you can best achieve interoperability by adhering to the guidelines set forth by the Web Services Interoperability (WS-I) organization in their Basic Profile version 1.0. In this book, we will show you how to write Web services that conform to those guidelines. Focusing on interoperability means there are some Web service issues that fall outside the scope of the discussion. These issues include security, performance optimization, scalability, and bandwidth conservation.

For information on developing Web services, see the "More Information" section in this chapter.

(7 printed pages)

Contents

How to Use this Book
Documentation Conventions
The Impetus Behind the WS-I
More Information

How to Use this Book

This book is divided into five chapters. Here is a brief description of what each chapter contains.

Chapter 1, Introduction

This chapter discusses the WS-I. It includes the following topics:

• Why the WS-I was formed
• The organizational structure of the WS-I
• The problems the WS-I addresses, and those it does not
• The deliverables the WS-I provides

Chapter 2, The WS-I Deliverables

To encourage interoperability, the WS-I is creating a series of profiles, which will define how the underlying components of any Web service must work together. Chapter 2 discusses the first of these profiles, called the Basic Profile, and includes the following topics:

• The Basic Profile's underlying principles
• An explanation of the WS-I usage scenarios
• An explanation of the WS-I sample application, which demonstrates how to write a compliant Web service
• An explanation of the testing tools, which check that your implementation follows the Basic Profile guidelines

Chapter 3, How to Apply the Basic Profile

This chapter lists some general practices you should follow for writing Web services or clients that conform to Basic Profile.

Chapter 4, Applying Basic Profile Rules When Implementing Web Services

This chapter assigns each of the profile's rules to one of four possible levels of compliancy and, on a rule-by-rule basis, shows how to adjust your code to make your Web service comply with the profile's rules.

Chapter 5, Applying Basic Profile Rules When Consuming Web Services

This chapter assigns each of the profile's rules to one of four possible levels of compliancy and, on a rule-by-rule basis, shows how to adjust your code to make your Web service client comply with the profile's rules.

Appendix A

Appendix A groups the Basic Profile's rules according to their level of compliancy for implementing a Web service.

Appendix B

Appendix B groups the Basic Profile's rules according to their level of compliancy for implementing a Web service client.

Documentation Conventions

This guide uses the style conventions and terminology shown in Table 1.1.

Table 1.1 Document Conventions

The Impetus Behind the WS-I

Simply put, Web services are programs that expose services to clients. However, unlike other distributed computing systems that include their own communications protocol, Web services are, as their name implies, adapted to the Web, and use Web-based standards. Web services, in essence, make the Internet a programming library available to developers worldwide.

Software and hardware vendors alike are rushing Web services products to market. The widespread adoption of core standards, such as XML, SOAP, WSDL, and UDDI, represents a significant breakthrough in the industry. Applications can now be built using a combination of components from multiple suppliers. However, for Web services to truly fulfill their promise, they must be interoperable. An interoperable Web service is one that works across platforms, applications, and languages as well as with Web services from other vendors.

Interoperability requires consensus, a clear understanding of requirements, and adherence to specifications. In response to these needs, industry members formed the WS-I, whose goals are to:

• Provide education and guidance that will further the adoption of Web services
• Promote consistent and reliable practices that will help developers write Web services that are interoperable across platforms, applications, and programming languages
• Articulate and promote a common industry vision for Web services interoperability to ensure that Web services evolve in a systematic, coherent fashion

To achieve its goals, the WS-I employs a variety of strategies, including:

• Implementation and testing guidance
• Web services profiles

Implementation guidance advises developers on the best practices for using such primary Web service components as XML, SOAP, WSDL, and UDDI. Testing guidance is available in the form of test tools that verify if a Web service adheres to the conformance guidelines set forth by the WS-I.

Web service profiles collect key Web service specifications into meaningful groups and simplify the implementation of interoperable applications. By demonstrating how each of these standards relates to the others, profiles also promote the adoption of those standards. The WS-I plans to constantly improve the scope and definition of the profiles to reflect the growing maturity of the underlying standards and the demands of the market.

Note that the WS-I is not itself a standards body. Rather, it cooperates with other industry groups and acts as a point of integration for the standards they generate.

The WS-I maintains a web site at http://www.ws-i.org/.

Members of the WS-I include software vendors, enterprise customers, and anyone interested in promoting interoperable Web services. Members vote to approve the adoption and distribution of any materials developed by the working groups.

WS-I Deliverables

The WS-I provides four types of deliverables. These are:

• Profiles
• Test tools
• Use cases and usage scenarios
• Sample applications

Profiles

Profiles were created by the WS-I in response to the ever-growing number of interrelated specifications, all at different version levels and differing stages of development and adoption, and often with conflicting requirements. The group determined that developers needed some way of knowing which products supported what levels of specification. Profiles solve this problem. They contain lists of named and versioned Web services specifications, along with implementation and interoperability guidelines that recommend how the specified components should be used together to develop interoperable Web services.

Presently, there is one profile available called the Basic Profile. The Basic Profile deals with the following components:

• Messaging (SOAP/HTTP), which is the exchange of protocol elements, usually over a network, to allow Web service interfaces to communicate with each other.
• Description (WSDL), which is the mechanism through which Web service definitions are exposed and to which Web service implementers must conform when sending SOAP messages.
• Discovery (UDDI), which is the metadata enabling the advertisement of a Web service.
• XML Schema, which is how data definitions are structured in a SOAP document.
• XML 1.0, which is how XML data is serialized to a network stream or a file.

Test Tools

The test tools consist of a monitor and an analyzer. The monitor intercepts and records interactions either between Web services or with a Web service, treating the Web service and components with which it communicates as black boxes. It generates a log that is later processed by the analyzer. The analyzer verifies that the intercepted Web service interactions recorded in the log conform to a given profile. As input, it uses the implementation guideline assertions from the profile, WSDL and/or UDDI descriptions of the Web service under test, and the logs generated by the monitor. The analyzer's focus is on detecting instances where a Web service deviates from the profile rather than on verifying that every feature of a particular profile was implemented in the Web service.

Use Cases and Usage Scenarios

Within the context of a particular profile, use cases and usage scenarios capture, respectively, the business and technical requirements for using Web services in a particular situation. For the Basic Profile, these requirements were used by the sample applications group to produce a Technical Design and Implementation Specification for a sample application that describes the Web services needed, along with the necessary supporting resources such as WSDL files, XML schema, and UDDI Web service registrations. Use cases are provided that provide a framework for demonstrating the guidelines described in the profiles.

Sample Applications

Sample applications are implementations of applications that are built from use cases and usage scenarios. These implementations are expected for each of the major platforms currently available. Once development is nearly complete, members of the implementation working group will cross-test them to see if they are interoperable. Any problems that arise will be communicated to the profile group so that they can revise their documentation.

More Information

The Microsoft Developer's Network (MSDN) has a site specifically for Web services developers called the XML Web Services Developer Center. Some articles of immediate interest are:

• Web Service Basics
• Understanding XML Namespaces
• Getting Started with XML Web Services in Visual Basic .NET and Visual C#
• RPC/Literal and Freedom of Choice
• The Argument Against SOAP Encoding