1EdTech General Web Services Primer Version 1.0 Final Specification

Copyright © 2005 1EdTech Consortium, Inc. All Rights Reserved.
The 1EdTech Logo is a registered trademark of 1EdTech/GLC
Document Name: 1EdTech General Web Services Primer
Revision: 19 December 2005

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright ) 2005 1EdTech Consortium. All Rights Reserved.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/license.html.

The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Overview

The 1EdTech General Web Services specification promotes interoperability across web service based specification implementations on different software and vendor platforms. The principal component of the 1EdTech General Web Services specification is the Base Profile that identifies a core set of specifications that are to be used to produce a service-oriented architecture using Web Services. It is not a goal of the Base Profile to create a plug-and-play architecture for web services or to guarantee complete interoperability. The 1EdTech General Web Services Base Profile addresses interoperability in the application layer, in particular, the description of behaviors exposed via Web Services. The Base Profile can be extended using one or more of the 1EdTech General Web Services extension profiles. These extension profiles are the Addressing Profile, Security Profile and the Attachments Profile.

From a technical perspective, the 1EdTech General Web Services specification is produced to ensure that all of the services defined by 1EdTech Consortium (1EdTech/GLC) use a common, and thus compatible, message exchange infrastructure. A consequence of this is that the creation of a service specification is focused on the business process and the service methods required which realise that process. This is because the realisation of the service as a Web Service has been reduced to a computer-automated technique. Once a service has been defined using the 1EdTech/GLC specification methodology then the corresponding 1EdTech Binding Auto-generation Toolkit is used to create the corresponding web services binding.

Table of Contents

Overview

1. Introduction
1.1 Context for the General Web Services Specification
1.2 The General Web Services Specification
1.3 Structure of the Primer
1.4 References
1.5 List of Acronyms

2. General Web Services Profile
2.1 GWS Base Profile
2.2 GWS Addressing Profile
2.3 GWS Security Profile
2.4 GWS Attachments Profile

3. Using the Profiles

4. Creating a WSDL Binding of the Profiles

About This Document
List of Contributors

Revision History

Index

1. Introduction

1.1 Context for the General Web Services Specification

The objective of the 1EdTech General Web Services (GWS) specification is to provide a framework for guiding project teams looking to use web services as part of 1EdTech Consortium (1EdTech/GLC) specification development. A GWS service binding will provide a methodology and an application profile that meets the following criteria:

• Interoperability - artefacts produced under the GWS activity will seek to identify mechanisms and standards that promote interoperability between web service specification implementations across different software and operating system platform;
• Efficiency - artefacts produced under the GWS activity will be designed to help other 1EdTech specification activities efficiently and effectively evaluate web services protocols as they pertain to the functional requirements;
• Consistency - artefacts produced under the GWS activity will be designed to facilitate the implementation of consistent approach to the implementation of web service protocols across 1EdTech activities and specifications;
• Flexibility - artefacts produced under the GWS activity will be flexible enough to adapt to evolving web service protocols such as 'SOAP' and to work with a variety of binding methods for web services such as Web Services Description Language (WSDL);
• Practicality - artefacts produced under the GWS activity will seek to facilitate vendor's ability to implement 1EdTech/GLC based Web Service solutions and interoperability across platforms and vendor implementations of web service protocols.

1.2 The General Web Services Specification

The 1EdTech General Web Services specification consists of the following documentation:

• 1EdTech GWS Primer - the introduction and overview to the 1EdTech GWS specification (this document);
• 1EdTech GWS Base Profile [Base, 05] - the underlying profile that defines the core protocols and message choreography;
• 1EdTech GWS Addressing Profile [Address, 05] - extension of the GWS Base Profile to enable transport independent end-to-end addressing;
• 1EdTech GWS Security Profile [Secure, 05] - extension of the GWS Base Profile to enable the support of different security architectures;
• 1EdTech GWS Attachments Profile [Attachments, 05] - extension of the GWS Base Profile to enable the exchange on non-XML information.

The bindings for the 1EdTech GWS specification are created using the 1EdTech Binding Auto-generation Toolkit (I-BAT). The I-BAT is used to enable a service specification whose information model is created using the 1EdTech approach to have the corresponding WSDL binding automatically generated from that model. The I-BAT consists of:

• I-BAT Manual [I-BAT, 05] - the documentation that explains how to use the I-BAT (this includes the installation guide, user manual, tutorial and reference manual);
• I-BAT Tool-kit - the set of templates for the development of the model of the specification (using the Unified Modelling Language) and the corresponding XML Style-sheets (XSLs) that are used to convert the model to the WSDL binding.

Finally, reference implementation source code is supplied to simplify the adoption of the 1EdTech GWS specification. The reference implementation materials consist of:

• .NET reference implementation - the source code developed to implement 1EdTech GWS within the .NET framework;
• J2EE reference implementation - the source code to implement the 1EdTech GWS using Java.

1.3 Structure of the Primer

The structure of the rest of this document is:

1.4 References

1.5 List of Acronyms

2. General Web Services Profile

2.1 GWS Base Profile

The 1EdTech GWS Base Profile [Base, 05] promotes interoperability across web service based specification implementations on different software and vendor platforms. The Base Profile is focused on a core set of web service specifications and the most common problems experienced implementing the identified Web Service specifications. It is not a goal of the General Web Services Base Profile to create a plug-and-play architecture for web services or to guarantee complete interoperability. The General Web Services Base Profile addresses interoperability in the application layer, in particular, the description of behaviors exposed via Web Services. The General Web Services Base Profile assumes the interoperability of the lower layer protocols is sufficient. The information exchange model for the 1EdTech GWS is shown in Figure 2.1.

The salient feature of this model is that the lower level profiles are primarily responsible for defining the 'Messaging Infrastructure'. Once an 1EdTech/GLC service information model has been defined the binding rules are applied to create the messaging choreography. The other advantage of these binding rules is that the corresponding web service adapter for different services have many similar features thereby enabling a common web services adapter framework to be created.

The 1EdTech GWS Base Profile is based upon the Web Services Interoperability Organization (WS-I) Basic Profile v1.1 [WSI, 04a] and the WS-I Simple SOAP Binding Profile v1.0 [WSI, 04b]. The 1EdTech GWS Base Profile is defined in Table 2.1. The only difference between the 1EdTech profile and that of the WS-I Basic Profile is that the Universal Description Discovery & Integration (UDDI) specification is not included in the 1EdTech/GLC profile due to the limited availability of UDDI-based repositories. The WS-I Basic Profile consists of a set of non-proprietary Web Services specifications, along with clarifications and amendments to those specifications that promote interoperability. The WS-I Basic Profile has been selected as the basis for the 1EdTech GWS Base Profile because it is has wide adoption in many different business sectors.

It is recognized that SOAP v1.2 and WSDL v2.0 are available as later versions of the SOAP and WSDL specifications respectively. SOAP v1.2 and WSDL v2.0 will be considered for future revisions.

2.2 GWS Addressing Profile

The 1EdTech GWS Addressing Profile [Address, 05] extends the 1EdTech GWS Base Profile to allow transport-independent end-to-end addressing. The 1EdTech GWS Addressing Profile recommends the usage of the WS-Addressing standard from W3C. The WS-Addressing standard enables a SOAP message to be extended to contain the source of the information, the final destination address, the specific endpoint at the destination and instructions for processing if delivery is not possible. Many other WS-*1 specifications rely upon the usage of WS-Addressing. The 1EdTech GWS Addressing Profile describes how the addressing information is inserted in the SOAP header and how the 'endpoint reference' is defined. The 'endpoint reference' is used to provide an identifier that pinpoints a particular instance of a service. In most cases the 'endpoint reference' is dynamically generated from the properties defined in the associated WSDL file.

2.3 GWS Security Profile

The 1EdTech GWS Security Profile [Security, 05] extends the 1EdTech GWS Base Profile to allow the support of a range of secure architectures. The WS-I is developing their Basic Security Profile but this profile is too immature for immediate adoption by 1EdTech/GLC. Therefore, the 1EdTech GWS Security Profile contains only general recommendations and these will be revisited once the WS-I Basic Security Profile has matured. Security for web services, as with any network-oriented information technology, is vital. Web services security builds on existing security standards for confidentiality, integrity, non-repudiation, authentication and authorization at the transport, platform and application level. The key to security is analyzing the potential threats and implementing countermeasures to reduce risk to an acceptable level. Selecting the appropriate countermeasures and defining the acceptable level of risk is best done on an individual basis for each implementation. Securing the network traffic is a simple way to provide message integrity and confidentiality between points. Mechanisms for securing network traffic include Secure Socket layer, Transport Layer Security, Virtual Private Network and IP Security.

2.4 GWS Attachments Profile

The 1EdTech GWS Attachments Profile [Attachments, 05] extends the 1EdTech GWS Base Profile to support the exchange of non-XML information in the SOAP messages. This enables MS Word documents, images, zip files, etc. to be exchanged using SOAP messages. Non-XML information is attached to the SOAP messages using the Message Transmission Optimization Mechanism (MTOM). MTOM combines the transport efficiency of SOAP with Attachments (SWA) and the flexibility of Base64 encoding. WS-I recommends the usage of SWA however SWA is based upon an inefficient MIME encoding technique (as per email) and is incompatible with WS-Security (WS-Security will eventually form the basis of the 1EdTech Security Profile). MTOM uses the XML-binary Optimization Packaging (XOP) mechanism for efficiently placing non-XML content into MIME packages.

3. Using the Profiles

From a technical perspective, the 1EdTech GWS specification is produced to ensure that all of the services defined by 1EdTech/GLC use a common, and thus compatible, message exchange infrastructure. A consequence of this is that the creation of a service specification is focused on the business process and the service methods required which realise that process. This is because the realisation of the service as a Web Service has been reduced to a computer-automated technique. Figure 3.1 is a schematic representation of the relationship between an 1EdTech/GLC specification and the 1EdTech GWS.

In Figure 3.1 the key parts of this infrastructure are:

• 1EdTech/GLC XML Components - the application and common services components that are combined to create the e-learning system required. It is assumed that these components exchange information in the form of XML documents;
• XML-based Context - the XML documents are transformed to XML messages which are then mapped onto the common XML messaging infrastructure that is designed to support the required end-to-end services e.g. reliable data transfer, datagram, publish and subscribe, etc. WSDL is the context mapping language and the 1EdTech GWS defines how the service-description is transformed into the WSDL equivalent;
• XML-based Envelope - the common XML messaging system can be supported using several types of XML envelope encapsulation i.e. SOAP/SOAP with message attachments, etc. The 1EdTech GWS defines the message structure, choreography and other messaging considerations;
• Generic transport - the envelope is then transported across the network using an appropriate end-to-end file transfer protocol using the HyperText Transfer Protocol (HTTP);
• Communications network - this is the actual data network that is used to physically transport the data from one system to another. This will almost certainly be based upon the ubiquitous Internet Transmission Control Protocol/Internet Protocol (TCP/IP) combination providing seamless interworking between wire-line and wireless networks.

To use the 1EdTech GWS profiles the specification creators must make the following decisions:

• Which set of profiles are to be adopted i.e. is it just the Base Profile or will one or more of the extension profiles also be used (Security, Addressing and/or Attachments);
• The nature of the service in terms of being synchronous, asynchronous, polled, publish-and-subscribe, etc. This issue does not impact the service definition but is used to decide the final form of the service binding;
• The breakdown of the business process into its constituent services and the corresponding behaviours (this is the predominant activity for the specification creators and it is where the creative aspects of the work are undertaken).

The service(s) is created using an abstract representation that is then transformed into the corresponding Web Service binding. All of this process is supported using the 1EdTech specification development tools developed specifically for this need.

4. Creating a WSDL Binding of the Profiles

The process for creating a WSDL binding for a service that is based upon the 1EdTech GWS Base Profile is shown schematically in Figure 4.1. The steps in the process are:

1. The Information Model for the service must be defined using the 1EdTech Service Unified Modelling Language Profile [I-BAT, 05]. This profile describes how the Unified Modelling Language (UML) must be used to create a description of the specification that can be used by the 1EdTech auto-generation tools. The specification is created without explicit identification of the type of communications model to be supported by the binding i.e. the nature of the communication model supported is defined when the binding is created;
2. The UML description is made available as an XML Meta-data Interchange (XMI) file i.e. this is an XML instance that conforms to the XMI specification. At the present time only XMI files that have been created by the Poseidon tool, v2.5 or later, are valid. The Poseidon tool creates a '.zuml' file that must be unzipped and the XMI file within used as input to the I-BAT;

The XMI file is now used as input to the I-BAT. The XSL file 'UMLtoWSDLTransform.xsl' is applied to the XMI file, using an appropriate XSLT tool (Oxygen is the tool recommended by 1EdTech/GLC) to generate the WSDL files. The XSL files automatically create the full set of WSDL files using a predetermined naming convention for the corresponding directory structure, the name(s) of the services and the communications model. The generation process also creates a validation report text file that can be used to identify any problems that the I-BAT found while creating the binding files. The XSL 'WSDLtoHTML.xsl' is used to generate a HTML document that contains the description of the services defined by the WSDL.

The following points should be noted when using the I-BAT:

• The I-BAT creates several different sets of the binding that are categorised as:
  • Single file WSDL/XSD representation in which the WSDL and XSD descriptions are contained in a single file (this is the recommended binding as many of the WSDL-processing tools do not support the multiple file WSDL bindings)
  • Split file representation in which the WSDL and XSD descriptions are contained in separate files i.e. one file for the WSDL and a second file for the XSD
  • Split service representation in which the WSDL and XSD descriptions are contained in separate files i.e. two files for the WSDL (one for the abstract description and the other for the service specific description) and a third file for the XSD
  • Multiple file representation in which the WSDL descriptions are contained in two files (one for the abstract description and the other for the service specific description) and the XSD is spread over several linked files;
• The I-BAT will attempt to generate the binding files irrespective of any problems described in the validation report;
• The I-BAT cannot be used to correct problems with the UML-based service description. Any problems in the Information Model must be corrected using the appropriate UML authoring tool. The binding creation process must then be repeated using the new XMI file;
• Any hand edits of the WSDL/XSD files will be lost when new binding files are created.

The I-BAT is made available to support the development of non-1EdTech specifications. All of the templates and XSLs are supplied with the toolkit.

About This Document

List of Contributors

The following individuals contributed to the development of this document:

Revision History

Index

B
Base Profile 1, 2, 3, 4

C
Context 1, 2

I
1EdTech Auto-generation Binding Tool 1, 2, 3, 4
1EdTech General Web Services 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Addressing Profile 1, 2, 3
Attachments Profile 1, 2, 3
Base Profile 1, 2, 3, 4, 5, 6, 7
Security Profile 1, 2, 3
Internet Protocol 1, 2
IP Security 1
 

P
Protocols
HTTP 1, 2, 3
IP 1, 2, 3
IPSEC 1
SOAP 1, 2, 3, 4, 5
TCP 1, 2
 

S
Security 1, 2, 3, 4, 5
SOAP 1, 2, 3, 4, 5
SOAP with Attachments 1, 2

T
TCP 1, 2
Transmission Control Protocol 1, 2
Transport Layer Security 1

U
UDDI 1, 2
Unified Modelling Language 1, 2, 3, 4
UML 1, 2, 3
 

V
Virtual Private Network 1

W
W3C 1, 2
Web Services 1, 2, 3, 4, 5, 6
SOAP 1, 2, 3, 4, 5
WSDL 1, 2, 3, 4, 5, 6, 7
WS-Security 1
Web Services Interoperability Organization 1, 2, 3
WSDL 1, 2, 3, 4, 5, 6, 7
WS-I
Basic Profile 1
Basic Security Profile 1
Simple SOAP Binding Profile 1, 2
WS-I Basic Profile 1
WS-I Basic Security Profile 1
WS-I Simple SOAP Binding Profile 1, 2
WS-Security 1
 

X
XMI 1, 2, 3
XML 1, 2, 3, 4, 5
XML Schema 1, 2
XML Schema Definition 1
XSD 1, 2, 3
XSLT 1