Best Practices in Web Service Style, Data Binding and Validation (for use in Data-Centric Applications) David Meredith, Asif Akram, Rob Allan CCLRC Daresbury Laboratory

Why do we need to consider WS best practices The initial SOAP tool kit started to ship around 1998 and it is now 2005/2006 and we still havent really achieved web service ubiquity that everybody was promising (Ted Neward – BEA Technical Director, former Editor in chief of theserverside.com, INETA speaker and general prognosticator of rabid opinions in both the Java and.NET space) Related comments: WS are CORBA with angle brackets Most WS we see are simple stock quote services

Question: What has led to these comments being made ? Answer: The popularity of RPC style Web service style and their inherent limitations, and some bad practices in WS development * WSDL generators can introduce technical dependencies upon the implementation language – this can lead to serious interoperability issues across different platforms, e.g. Java and.NET. Defeats the main aim of WS as a cross-domain and platform independent internet technology (better to use more efficient intranet technologies, RMI). RPC has limitations for the constraint/validation of complex data. * Check out the technical talk pod cast on entitled Web Services and Security, 2006

1)Choice of WS style RPC/encoded, RPC/literal, Document/literal wrapped WS style is at the heart of WS best practices and influences all other implementation choices 2) Abstraction of data 3) When to use loosely or strongly typed WS 4) When to perform data binding and validation 5) Approach to writing WS Choices in WS Development that require some best practice thought

1) Choice of Web Service Style RPC-encoded (depreciated) Uses SOAP encoding scheme to serialize complex objects into XML. The contains multiple multiref elements (WS-I recommends that the should contain a single nested sub- element). Produces an XML document that doesnt really look like XML, it doesnt obey the XPath rules all that well (XSLT transformation is problematic). Is not WS-I compliant – Avoid ! (its only use is for legacy purposes)

RPC/literal No encodingStyle attribute – 100% XML Schema. WS parameters are wrapped within an element named after the WS operation. The has only one nested sub-element (WS-I compliant). Validation can be problematic - must account for the RPC element naming conventions + WSDL tns (rather than solely binding and validating plain data-model XML instance documents). Many SOAP engines actually drop schema defined namespace definitions in SOAP message – this means all elements share the WSDL ns (validation becomes impossible). 1) Choice of Web Service Style

Document/literal (wrapped) Messaging with plain XML instance documents (rather than invoking operations with parameters serialized into XML - RPC). For multiple XML docs, nest them within a single wrapper element (which can be simply added to the section of the WSDL file). The has only one nested sub-element (WS- I compliant). Doc style SOAP messages are very similar to RPC/literal messages as both produce a single nested element with the. The main difference is that each element is fully qualified with a Schema defined ns (enables validation of complex data).

Document/literal wrapped style is best, especially if you need to describe, model and validate complex data. Best Practice 1 (Web Service Style)

1) Choice of WS style (RPC or Document) 2) Abstraction of data Applies to both the RPC/literal and Doc style. 3) When to use loosely or strongly typed WS 4) When to perform data binding and validation 5) Approach to writing WS (code first or WSDL first) Choices in WS Development that require some best practice thought

2) Data type abstraction Separating the XML Schema elements and complex types defined within the section of the WSDL file into separate files. Recommended as data can be modelled in different documents according to different namespace and domain / data requirements … <wsdl:definitions … <xsd:import namespace=… schemaLocation="BulkMRFinal.xsd"/>.. Schema1.xsdSchema2.xsd

2) Data Model Abstraction (Benefits) Separation of roles – Data model can be developed in isolation from WSDL. Schema / data model re-usability – Share and re-use schema rather than re- designing schema for each new WS. Isolation of changing components – Data model can be subject to change. Its isolation limits the impact on other WS components such as concrete WSDL file. Data model avoids dependencies on WSDL + SOAP namespaces – Good data model design. Full Schema functionality – XML Schema is powerful (e.g. xsd patterns/regular-expressions, optional elements, enumerations, type restrictions etc) Extensible Modelling – Schema can be extended without breaking software that uses the original schema through the use of xsd:any / xsd:anyType (wildcard / placeholder for extending schema where necessary).

Abstract the XML Schema(s) used in the section of the WSDL file into separate files. 1)Model data logically in separate schema files with different namespaces as required by the data model. 2)Combine separate Schema files as required using and 3)Import the schema file(s) into the WSDL file. 4)Reduces the size + complexity of the WSDL file. Best Practice 2 (Data Model Abstraction)

1) Choice of WS style (RPC or Document) 2) Data type abstraction 3) When to use loosely or strongly typed WS 4) When to perform data binding and validation 5) Approach to writing WS Choices in WS Development that require some best practice thought

3) When to use loose or strongly typed WS A strongly typed WS: Defines a WSDL with a complete definition of a WS operations input and output messages in XML schema with tight constraints on the allowed values. xsd:patterns, xsd:restrictions, xsd:enumerations, xsd:sequences etc Advantages: Well defined service interface – all info necessary to invoke the service is encapsulated within the WSDL (client friendly, automation friendly) Strong control on the data that enters the business logic of the service Disadvantages: Requires a working knowledge of XML Schema Resistive to change in data model

A loosely typed WS: Uses generic data types in the WSDL which are used to wrap data of other formats: String – can wrap markup fragments (e.g. xml, name-value pairs, SQL) xsd:any / xsd:anyType - placeholders for embedding arbitrary XML SOAP attachments (used to send data of any format, e.g binary) 3) When to use loose or strongly typed WS Advantages: Flexible – single WS can handle multiple types of message + message data Easy to develop Disadvantages: Incomplete WSDL interface - Requires manual negotiation between client and service to establish format of data wrapped by loose type. Prone to message exceptions (requires WS to be v.tolerant in what it accepts)

Best Practice 3 (When to use loose or strong WS typing) It is practical to mix loose and strong typing where necessary to suit your application needs (a single WSDL can combine loose and strong typing) Loose typing useful when prototyping services, strong typing is usually better for production services.

1) Choice of WS style (RPC or Document) 2) Data type abstraction 3) When to use loosely or strongly typed WS 4) When to perform data binding and validation: a)Rely on the SOAP engine before invocation of WS operation b)Bind and validate the XML payload after invocation 5) Approach to writing WS (code first or WSDL first) Choices in WS Development that require some best practice thought

/* WS operation – SOAP engine binds and validates xml */ public ArrayOfXsdString executeBulkMR(String mrprogram, String sequence, PdbIgnoreCodes ignore, Integer pack){ // TODO: implement business logic, return valid response } a)Use SOAP engine to bind and validate XML payload before the service is invoked (passed an object representation of wsdl:message): Advantages: Simplicity: Hidden from binding and validation process Disadvantages: Restricted choice of binding / validation framework (e.g. JAX-WS/ JAX-B) Semi-standardized data bindings (e.g. Axis 1.2 not 100% schema compliant). Requires manual un-marshalling of objects back into XML if the raw XML is required for out-of-band processes.

Advantages: Choice of preferred data b/v framework (e.g. cursor functionality of XmlBeans) Clear separation of roles (b/v framework and SOAP-engine have well defined data-centric and communication-centric roles. On-Demand XML doc construction and validation for out-of-band processes. Disadvantages: Complexity: Developer responsible for parsing, binding + validating data (made easier with good b/v frameworks inc. JAX-B, XMLbeans rather than using manual APIs inc. DOM and SAX). /* WS operation – bind and validate xml within the operation */ public void executeBulkMR(SOAPEnvelope req, SOAPEnvelope resp){ // TODO: business logic left to bind, validate and extract data // TODO: implement business logic, build response envelope } b) Bind and validate the XML within the WS operation

Best practice 4 (When to perform data binding and validation) If you rely on the SOAP engine to perform data binding and validation ensure its internal binding and validation framework is 100% W3C Schema compliant. JAX-RPC Apache Axis 1.2 (not 100% Schema compliant) JAX-WS (JAX-B) Xfire (supports pluggable binding frameworks) Axis2 (XmlBeans) If you require the raw XML and require on-demand document construction and validation, is better to bind and validate XML within the WS operation when needed.

1) Choice of WS style (RPC or Document) 2) Data type abstraction 3) When to use loosely or strongly typed WS 4) When to perform data binding and validation 5) Approach to writing WS a) Code first (bottom up) b) WSDL first (contract driven) Choices in WS Development that require some best practice thought

a) Code first or bottom up approach (generate WSDL file from the WS operation – e.g. Java2WSDL / wsgen) Advantages: Simple Disadvantages: WSDL files created from src code are always loosely typed (e.g. a src code: String is just a String – cant impose xsd:patterns or xsd:restrictions if starting with a String). WSDL auto-generation tools can introduce technical dependencies upon implementation language ! Not all language specific data types can be mapped into interoperable XML (the Object – XML mismatch).

b) WSDL first or contract driven approach (generate the WS operation from the WSDL file – e.g. WSDL2Java / wsimport) Advantages: Authored WSDL can be strongly and loosely typed where necessary Interoperability issues between different languages are avoided if starting with plain XML: Can auto-generate service implementation classes from WSDL. Disadvantages: Developer requires a reasonable knowledge of XML Schema + WSDL Best Practice 5 – Author WSDL first (contract driven)

Best Practice 1 Document/literal wrapped style Best Practice 2 Abstract XML Schema types from the WSDL Best Practice 3 Use strong and loose typing where appropriate Best practice 4 Use 100% W3C Schema compliant data b/v frameworks Use separate b/v framework for out-of-band processes Best Practice 5 – Author the WSDL first Summary: Is a recent shift to Document style WS over RPC e.g. Changing naming conventions (JSR 224 renamed JAX-RPC to JAX-WS) Deprecation of SOAP-encoding