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 haven’t 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 ‘http://www.theserverside.com’ entitled
‘Web Services and Security, 2006’
Choices in WS Development that require
some ‘best practice’ thought
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
1) Choice of Web Service Style
RPC-encoded (depreciated)
• Uses ‘SOAP encoding’ scheme to serialize complex objects into XML.
• The <soap:Body> contains multiple ‘multiref’ elements (WS-I
recommends that the <soap:Body> should contain a single nested subelement).
• Produces an XML document that doesn’t really look like XML, it doesn’t
obey the XPath rules all that well (XSLT transformation is problematic).
• Is not WS-I compliant – Avoid ! (its only use is for legacy purposes)
1) Choice of Web Service Style
RPC/literal
• No ‘encodingStyle’ attribute – 100% XML Schema.
• WS parameters are wrapped within an element named after the WS
operation. The <soap:Body> 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 <wsdl:types> section of the
WSDL file). The <soap:Body> has only one nested sub-element (WSI compliant).
• Doc style SOAP messages are very similar to RPC/literal messages
as both produce a single nested element with the <soap:Body>. The
main difference is that each element is fully qualified with a Schema
defined ns (enables validation of complex data).
Best Practice 1 (Web Service Style)
Document/literal wrapped style is best, especially if
you need to describe, model and validate complex
data.
Choices in WS Development that require
some ‘best practice’ thought
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)
2) Data type abstraction
Separating the XML Schema elements and complex types defined within the
<wsdl:types> 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 …
<wsdl:types>
<xsd:schema …>
<xsd:import namespace=“…”
schemaLocation="BulkMRFinal.xsd"/>
</xsd:schema>
</wsdl:types>
..
<schema…>
<xsd:include
schemaLocation=“schema1.xsd”/>
<xsd:import
schemaLocation=“schema2.xsd”/>
…
</schema>
</wsdl:definitions>
Schema1.xsd
Schema2.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 redesigning 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).
Best Practice 2 (Data Model Abstraction)
Abstract the XML Schema(s) used in the <wsdl:types> 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
<xsd:include> and <xsd:import>
3) Import the schema file(s) into the WSDL file.
4) Reduces the size + complexity of the WSDL file.
Choices in WS Development that require
some ‘best practice’ thought
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
3) When to use ‘loose’ or ‘strongly’ typed WS
A strongly typed WS:
Defines a WSDL with a complete definition of a WS operation’s 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
3) When to use ‘loose’ or ‘strongly’ typed WS
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)
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.
Choices in WS Development that require some ‘best
practice’ thought
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)
a) Use SOAP engine to bind and validate XML payload before
the service is invoked (passed an object representation of wsdl:message):
/* 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
}
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.
b) Bind and validate the XML within the WS operation
/* 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
}
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 API’s inc. DOM and SAX).
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.
Choices in WS Development that require
some ‘best practice’ thought
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’)
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 – can’t 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)
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’
•
•
•
•
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
Descargar

Best Practices in Web Service Style, Data Binding and