IMS General Web Services Base Profile Version 1.0 Final Specification

Copyright © 2005 IMS Global Learning Consortium, Inc. All Rights Reserved.
The IMS Logo is a registered trademark of IMS/GLC
Document Name: IMS General Web Services Base Profile
Revision: 19 December 2005

Executive Summary

The General Web Service Base Profile provides a basic structure for the definition of Web Services. It consists of a set of non-proprietary Web services specifications, along with clarifications and amendments to those specifications that promote interoperability. The General Web Services Base Profile addresses the most common problems experienced when implementing web service specifications. The General Web Services Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful.

The General Web Services Base Profile promotes interoperability for web service based specification implementations on different software and vendor platforms. The Base Profile focuses 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 Service Base Profile is derived from the Web Services Interoperability Basic Profile v1.1 and the Web Services Interoperability Simple SOAP Binding Profile v1.0. The IMS Global Learning Consortium (IMS/GLC) recommendations for the General Web Service Base Profile are to adopt:

• XML Schema V1.0 - all data models in IMS specifications will be defined in terms of XML Schema (XSD);
• HTTP V1.1 - the Hypertext Transfer Protocol (HTTP) is the mandated protocol binding for the SOAP messages;
• SOAP V1.1 - SOAP is the mandated messaging protocol;
• WSDL V1.1 - an instance of the service is defined using Web Services Description Language (WSDL) v1.1.

The General Web Service Base Profile can be extended by the adoption of one or more support General Web Service profiles. Other IMS General Web Service documents describe profiles for Addressing (transport-neutral web service addressing), Attachments (sending non-XML documents with the SOAP messages) and Security (secure data exchange).

In principle, the SOAP-based binding for the web services supports many communications messaging models (the Information Model for an IMS/GLC specification is defined independently of the messaging nature, i.e., this is determined by the form of the Web Services Description Language binding). At the current time only one messaging model is supported:

• Synchronous - this is a request/response message exchange in which the service initiator is blocked until the response message is received

Further messaging models will be added as and when required, i.e., asynchronous, polled, and publish and subscribe. There are three methods by which the functional capability of the base profile can be extended:

• Addition of new SOAP messages - the addition of new business transactions and the usage of new messaging models requires the creation of new SOAP messages;
• Extensions to the SOAP header - the current IMS General Web Service Base Profile makes use of the SOAP header to contain the application-to-application transaction status information. It is recommended that proprietary extensions to the SOAP header maintain the current usage patterns;
• Extensions in the data contained within the SOAP body - the SOAP body contains the XML instance that is used to represent the parameters defined for the transaction operations in the specification. There may be a need to add new parameters or to extend the XML structures of the current parameters.

The IMS General Web Service documentation is augmented with a substantial set of support tools that enables organizations to create their own Web Services Description Language bindings based upon the IMS General Web Service. Other materials enable .NET and J2EE implementations to be built based upon reference implementations of the IMS General Web Service.

Table of Contents

1. Introduction

1.1 Scope and Context

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

• Interoperability - Artefacts produced under the General Web Services 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 General Web Services activity will be designed to help other IMS project teams efficiently and effectively evaluate web services protocols as they pertain to the functional requirements of the project team;
• Consistency - Artefacts produced under the General Web Services activity will be designed to facilitate the implementation of consistent approach to the implementation of web service protocols across IMS project teams and specifications;
• Flexibility - Artefacts produced under the General Web Services activity will be flexible enough to adapt to evolving web service protocols such as 'SOAP'/'SOAP with message attachments' and to work with a variety of binding methods for web services such as Web Services Description Language (WSDL);
• Practicality - Artefacts produced under the General Web Services activity will seek to facilitate vendor's ability to implement IMS/GLC based Web Service solutions and interoperability across platforms and vendor implementations of web service protocols.

The General Web Services Base Profile (GWSBP) provides a basic structure for the definition of Web Services. It consists of a set of non-proprietary Web Services specifications, along with clarifications and amendments to those specifications that promote interoperability. The General Web Services Base Profile addresses the most common problems experienced implementing web service specifications. The General Web Services Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful. The General Web Services Base Profiles will contain syntax conventions consistent with IMS Specification Development Methodology [SpecDev, 03] and Abstract Framework [AbsASCs, 03], [AbsGloss, 03], [AbsWhite, 03].

The General Web Services Base Profile 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.

Included in this document is a set of recommendations and best practices including how to extend the General Web Services Base Profile. The extensions will have guidance for creating Web Services binding for the Abstract Framework's common services layer such as error handling, security, manifest, context and routing. IMS/GLC has defined a complementary set of profiles that build upon the Base Profile to incorporate more of the Web Services standards and specification developed by the World Wide Web Consortium (W3C). Therefore, this document should be read in conjunction with the set of IMS General Web Services extension profiles [GWS, 05a], [GWS, 05b], [GWS, 05c] and the IMS General Web Services WSDL Binding Guidelines [GWS, 05d]. The terms of reference for the creation of both documents are defined in the original project charter [GWS, 03a].

1.2 Structure of this Document

The structure of this document is:

1.3 Nomenclature

1.4 References

2. Context for the GWS Profiles

2.1 Syntax Conventions

2.1.1 Recommendations from the IMS Abstract Framework

All IMS service-oriented specifications will be defined in the context of the IMS Abstract Framework [AbsWhite, 03], [AbsASC, 03], [AbsGloss, 03]. Web services are one possible binding of an IMS service-oriented specification. Section 4 of this document describes how an IMS specification as defined by an Information Model is related to web services through the appropriate 'Infrastructure Binding'.

2.1.2 Recommendations from the International Conformance Program

The IMS International Conformance Program is responsible for defining how a particular information model and binding is constrained to support a particular domain in the form of an Application Profile Guidelines [APG, 05a], [APG, 05b]. Support for Conformance Testing will be added where appropriate, e.g., the WS-I enables conformance statements to be added to a WSDL file.

2.1.3 Recommendations from the IMS Binding Auto-generation Toolkit

The IMS Binding Auto-generation Toolkit document describes how the Unified Modelling Language (UML) is to be used to document an IMS information model [GWS, 05e]. The UML description is designed to facilitate the corresponding bindings, i.e., the UML description is not designed from the perspective of implementation as an Application Programming Interface (API). The UML description is also made available as an XML Metadata Interface (XMI) file; this enables tools to import the UML description and generate the corresponding code stubs. IMS has developed XML Stylesheet Language Transformations (XSLT) files to support automated UML conversion to WSDL, etc. The usage of these XSLTs and the corresponding tool is explained in the IMS Binding Auto-generation Toolkit Manual [GWS, 05e].

2.1.4 Recommendations from W3C Web Service Architecture

The Web Service Architecture (WSA) is a normative document that seeks to provide a context and model for understanding Web services and to facilitate placing Web services specifications and technologies within a larger Web Services framework and with other technologies outside of WSA. The WSA's goal is to promote interoperability through the common definition of a web service and its core concepts and relationships. The purpose of WSA is not to specify how Web services are implemented or to impose restrictions on combination or coordination of Web services. WSA provides discussion of the WSA's core concepts and relationships from various perspectives. Where appropriate, IMS will use the WSA in the IAF.

For more information on the Web Services Architecture, go to W3C Web Services Architecture (http://www.w3.org/TR/ws-arch/).

2.1.5 Recommendations from Web Services Interoperability Basic Profile

The IMS GWS Base Profile is based upon the WS-I Basic Profile v1.1 [WSI, 04a] and the WS-I Simple SOAP Binding Profile v1.0 [WSI, 04d]. The WS-I Basic Profile is shown in Table 2.1.

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.. It should be noted, that from the perspective of adopted specifications, the combination of the WS-I Basic Profile v1.1 and Simple SOAP Binding Profile v1.0 is identical to the WS-I Basic Profile v1.0a [WSI, 03].

2.2 Core Technologies

2.2.1 XML

XML 1.0 (Third Edition) is the core data representation technology adopted for the binding of IMS specifications [XML, 04]. An IMS data-model oriented information model can be defined as a hierarchy. Hierarchical models are convenient for representing data consisting of many elements and sub-elements. XML is perfectly suited for representing hierarchical models.

2.2.2 XML Schemas

XML Schema Definition (XSD) is the primary XML binding control document format of IMS (at present these bindings are working to the May 2001 version of XML Schema) [XSD, 01]. The XSD defines elements, their content models, and attributes. It also defines the standard IMS vocabularies. The XSD defines the element types and attribute groups separately from the elements. The key recommendations for XML Schema with respect to the Base Profile are:

1. When used in the context of SOAP messages all data constructs should be defined as elements. Attributes should not be used. This follows the recommendation of the WS-I;
2. All data types should be defined as 'Global'. The usage of 'Local' data types causes problems for some of the WSDL import tools, e.g., Axis;
3. All data types should have the character string ".Type" at the end of their name. This avoids naming conflicts between instances and their types.

2.2.3 SOAP

SOAP is a messaging protocol for XML documents which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment [SOAP, 03a], [SOAP, 03b]. It is a stateless, one-way message exchange mechanism, but applications can create more complex interaction patterns (e.g., request/response, request/multiple responses, etc.) by combining such one-way exchanges with features provided by an underlying transport protocol and/or application-specific information. SOAP provides the framework by which application-specific information may be conveyed in an extensible manner. Also, SOAP provides a full description of the expected actions taken by a SOAP processor on receiving a SOAP message.

A SOAP message contains two SOAP-specific sub-elements within the overall Envelope: the 'Header' and 'Body'. The contents of these elements are application defined and not a part of the SOAP specifications, although the latter does have something to say about how such elements must be handled. The 'Header' is optional. Headers have been designed in anticipation of various uses for SOAP, many of which will involve the participation of other SOAP processing nodes along a message's path from a sender to an ultimate receiver, to allow SOAP processors to exchange information to provide value-added services. These form the mechanism by which SOAP messages may be extended in an application-specific manner. The 'Body' is the mandatory element within an Envelope and this is where the main information conveyed in a SOAP message must be carried. The immediate child elements of a 'Header' are called header blocks, and represent some logical grouping of data that can be targeted at SOAP nodes encountered in the path of a message from a sender to a receiver.

The SOAP envelope is the container for the messages to be exchanged between the systems. These messages need to be physically transmitted across the communications system using an appropriate transport mechanism. In many cases the Hypertext Transport Protocol (HTTP) is used as this transport mechanism. The key recommendations for XML Schema with respect to the Base Profiles are:

1. Only bindings based upon SOAPv1.1 across HTTPv1.1 are supported;
2. The SOAP message body contains all of the parameters defined in the corresponding operation;
3. The status information is to be placed in the SOAP message header.

2.2.4 WS-Addressing

Web Services Addressing (WS-Addressing) defines two interoperable constructs that convey information that is typically provided by transport protocols and messaging systems. These constructs normalize this underlying information into a uniform format that can be processed independently of transport or application. The two constructs are 'endpoint references' and 'message information' headers. Both of these constructs are designed to be extensible and re-usable so that other specifications can build on and leverage endpoint references and message information headers.

A Web service endpoint is a (referenceable) entity, processor, or resource where Web service messages can be targeted. Endpoint references convey the information needed to identify/reference a Web service endpoint, and may be used in several different ways: endpoint references are suitable for conveying the information needed to access a Web service endpoint, but are also used to provide addresses for individual messages sent to and from Web services. To deal with this last usage case this specification defines a family of message information headers that allows uniform addressing of messages independent of underlying transport. These message information headers convey end-to-end message characteristics including addressing for source and destination endpoints as well as message identity.

2.2.5 Attachments for SOAP Messages

Attachments for SOAP messages are available in several forms:

1. SOAP with Attachments (SOAPwA) - SOAP With Attachments (SOAPwA) extends SOAPv1.1 by providing a MIME binding to support multiple message payloads, while ignoring the convention by which Remote Procedure Call (RPC) arguments may be marshalled and unmarshalled in XML. SOAPwA is especially suited for use cases where the two communicating parties are NOT located within the same organization, and the exchange paradigm is therefore more one of asynchronous Document Exchange across the Internet, than synchronous Remote Procedure Call within a single business (or University) enterprise;
2. WS-Attachments - this specification defines an abstract model for SOAP attachments and based on this model defines a mechanism for encapsulating a SOAP message and zero or more attachments in a DIME message. SOAP attachments are described using the notion of a compound document structure consisting of a primary SOAP message and zero or more related documents known as attachments;
3. Message Transmission Optimization Mechanism (MTOM) - MTOM is one of the W3C message attachment approaches to enable SOAP messages to contain non-XML objects. MTOM is a development of SOAPwA and is proposed as a replacement for the original SOAPwA specification.

The equivalent attachments recommendations for IMS GWS are defined in the IMS GWS Attachments Profile document [GWS, 05b].

2.2.6 WSDL

A WSDL document defines services as collections of network endpoints, or ports. In WSDL, the abstract definition of endpoints and messages is separated from their concrete network deployment or data format bindings. This allows the reuse of abstract definitions: messages, which are abstract descriptions of the data being exchanged, and port types that are abstract collections of operations. The concrete protocol and data format specifications for a particular port type constitute a reusable binding. A port is defined by associating a network address with a reusable binding and a collection of ports defines a service. Hence, a WSDL document uses the following elements in the definition of network services:

• Types - a container for data type definitions using some type system (such as XSD);
• Message -an abstract, typed definition of the data being communicated;
• Operation - an abstract description of an action supported by the service;
• Port Type -an abstract set of operations supported by one or more endpoints;
• Binding - a concrete protocol and data format specification for a particular port type;
• Port - a single endpoint defined as a combination of a binding and a network address;
• Service - a collection of related endpoints.

The key recommendations for WSDL with respect to the Base Profile are:

1. A separate set of WSDL files are defined for each type of communication mode being supported by the binding and there will be one form of the WSDL binding will be contained within a single physical file;
2. Alternatively there will be a split file binding in which the XSD information is defined in a separate file from that which contains the rest of the WSDL definition. The WSDL file imports the XSD definitions using the <xsd:import> construct;
3. The second alternative is to have the WSDL definition split into the service specific and abstract files plus the XSD, i.e., to create three separate but linked files. The service-specific file imports the abstract definitions using the <wsdl:import> construct and the abstract definitions file imports the XSD definitions using the <xsd:import> construct;
4. The final alternative is to have the two separate WSDL files plus several XSD files. The data schema and the message structure schema will be defined in separate files. The message structure XSD will contain all of the messages required for the different communication modes to be supported.

2.2.7 WS-Security

WS-Security defines a standard way to incorporate security information into a SOAP message using existing security standards for confidentiality, integrity, non-repudiation, authentication and authorization. WS-Security provides a method for representing security information in a SOAP message. WS-Security defines a way to pass security tokens, such as a simple username, SAML, X.509 certificates and Kerberos tickets, a mechanism using XML Signature to digitally sign all or part of a SOAP message, a mechanism using XML Encryption to encrypt part of a SOAP message and a method for attaching signature and encryption headers to a SOAP message. The equivalent security profile for IMS GWS is defined in the IMS GWS Security Profile [GWS, 05c].

2.2.8 Choreography

IMS plans to adopt the appropriate message and service choreography specifications, as opposed to creating its own. The underlying message choreography support in the GWS bindings are detailed in Section 5 of this document. Reliable messaging is only supported as a feature of the underlying communications infrastructure, e.g., through the usage of the Transmission Control Protocol (TCP). When stable, the following specifications will be adopted:

1. Web Services Reliable Messaging Framework (WS-Reliability) [WSR, 03] - the purpose of WS-Reliability is to address reliable messaging requirements, which become critical, for example, when using Web Services in B2B applications. SOAP [SOAP1.1] over HTTP [RFC2616] is not sufficient when an application-level messaging protocol must also address reliability and security. While security is getting traction in the development of Web Services standards, reliability is not. This specification is intended as an initial proposal for defining reliability in the context of current Web Services standards. The specification borrows from previous work in messaging an transport protocols, e.g., SOAP, and the ebXML Message Service. It proposes appropriate modifications to apply this work to Web Services;
2. Web Services Choreography Description Language Version 1.0 (W3C Working Draft 27 April 2004) - Web Services Choreography Description Language (WS-CDL) is an XML-based language that describes peer-to-peer collaborations of Web Services participants by defining, from a global viewpoint, their common and complementary observable behavior; where ordered message exchanges result in accomplishing a common business goal. The Web Services specifications offer a communication bridge between the heterogeneous computational environments used to develop and host applications. The Web Services Choreography specification is targeted for composing interoperable peer-to-peer collaborations between any type of Web Service participant regardless of the supporting platform or programming model used by the implementation of the hosting environment;
3. Business Process Execution Language for Web Services (BPEL4WS - BPEL4WS (or BPEL for short) is an XML-based standard for defining Web services can be combined to implement business processes [BPEL, 03]. It builds WSDL and XSD. BPEL provides an XML notation and semantics for specifying business process behavior based on Web Services. A BPEL4WS process is defined in terms of its interactions with partners. A partner may provide services to the process, require services from the process, or participate in a two-way interaction with the process. Thus BPEL orchestrates Web Services by specifying the order in which it is meaningful to call a collection of services, and assigns responsibilities for each of the services to partners. It can be used to specify both the public interfaces for the partners and the description of the executable process.

3. Base Profile Rules

3.1 IMS Base Profile

The IMS GWS Base Profile is defined in Table 3.1. The only difference between this profile and that of the WS-I Basic Profile/Simple SOAP Binding Profile is that the UDDI specification is not included in the profile.

3.2 Base Profile Rules Derived from WS-I Basic Profile

Table 3.2 summarizes the set of rules used in the WS-I Basic Profile v1.1 and their equivalent adoption status for the IMS GWS Base Profile. Within Table 3.2 the following conventions are used:

• The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119;
• Normative statements in the Profile, i.e., those impacting conformance, as outlined in "Profile Conformance", are presented in the following manner: RnnnnStatement text here, where "nnnn" is replaced by the statement number. Each statement contains exactly one requirement level keyword, e.g., "MUST", and one conformance target keyword, e.g., "MESSAGE".