- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 17 Jun 2005 21:46:51 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv13140/ws/desc/wsdl20
Modified Files:
wsdl20-primer.html wsdl20-primer.xml
Log Message:
complete incorporating DavidO contribution on Safety and HTTP binding
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.101
retrieving revision 1.102
diff -C2 -d -r1.101 -r1.102
*** wsdl20-primer.xml 17 Jun 2005 19:17:16 -0000 1.101
--- wsdl20-primer.xml 17 Jun 2005 21:46:48 -0000 1.102
***************
*** 1366,1370 ****
This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code>. The rest of the message content would go to the HTTP message body.</p></div3></div2>
<div2 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
! <p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> (<bibref ref="TAG-whenToUseGET"/>). From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was disussed in <specref ref="more-interfaces-op-attr"/>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>wsdlx:safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><ulist><item><p>If the WSDL 2.0 SOAP binding extension is used (<specref ref="more-bindings-soap"/>), with HTTP as the underlying transport protocol, then GET may be specified by setting:<glist><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></label><def><p>on the binding <code>operation</code> element, which causes GET to be used b default.</p></def></gitem></glist> </p></item><item><p>If the WSDL 2.0 HTTP binding extension is used directly (<specref ref="more-bindings-http"/>), GET may be specified by setting either:<glist><gitem><label><code>whttp:methodDefault="GET"</code></label><def><p>on the <code>binding</code> element; or</p></def></gitem><gitem><label><code>whttp:method="GET"</code></label><def><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element.</p></def></gitem></glist></p></item></ulist>
</div2></div1>
--- 1366,1402 ----
This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code>. The rest of the message content would go to the HTTP message body.</p></div3></div2>
<div2 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
! <p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> (<bibref ref="TAG-whenToUseGET"/>). From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was disussed in <specref ref="more-interfaces-op-attr"/>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>wsdlx:safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p>
!
! <ulist>
!
! <item><p>If the WSDL 2.0 SOAP binding extension is used (<specref ref="more-bindings-soap"/>), with HTTP as the underlying transport protocol, then GET may be specified by setting:<glist><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></label><def><p>on the binding <code>operation</code> element, which causes GET to be used by default.</p></def></gitem></glist> </p></item>
! <item><p>If the WSDL 2.0 HTTP binding extension is used directly (<specref ref="more-bindings-http"/>), GET may be specified by setting either:<glist><gitem><label><code>whttp:methodDefault="GET"</code></label><def><p>on the <code>binding</code> element; or</p></def></gitem><gitem><label><code>whttp:method="GET"</code></label><def><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element; or </p></def></gitem>
! <gitem><label><code>wsdlx:safe="true" </code></label><def><p> on the bound <code>interface operation </code>. When the above two items are not explicitly set, and when the bound interface operation is marked safe, the HTTP Binding will by default set the method to GET.</p></def>
!
! <p>For example, in the GreatH interface definition shown in <specref ref= "example-initial-interface"/>, the wsdlx:safe attribute is set to "true". The HTTP binding definition in <specref ref= "example-bindings-http"/> may take advantage of that and be simplified as below and still have the http method set to GET by default: </p>
!
! <example id="example-binding-safety">
! <head>Safety and HTTP Binding</head>
!
! <eg><![CDATA[
! <?xml version="1.0" encoding="utf-8" ?>
!
! <binding name="reservationHTTPBinding"
!
! interface="tns:reservationInterface"
!
! type="http://www.w3.org/2005/05/wsdl/http" >
!
! <operation ref="tns:opCheckAvailability"
!
! whttp:location="{checkInDate}"/>
!
! </binding>]]></eg>
! </example>
!
! </gitem>
!
! </glist></p></item></ulist>
!
</div2></div1>
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.72
retrieving revision 1.73
diff -C2 -d -r1.72 -r1.73
*** wsdl20-primer.html 17 Jun 2005 19:17:16 -0000 1.72
--- wsdl20-primer.html 17 Jun 2005 21:46:48 -0000 1.73
***************
*** 97,101 ****
<h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br>A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="toc">
<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL 2.0 Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#bascs-interface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> &nbs;3.2 <a href="#wsdl-schema">WSDL 2.0 Schema and Element Ordering</a><br> 3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br> 4.1 <a href="#more-types-schema-inline">Inlining XML Schema</a><br> 4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br> 5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 5.3 <a href="#more-interfaces-faults">Interface Faults</a><br> 5.4 <a href="#more-interfaces-operations">Interface Operations</a><br> 5.4.1 <a href="#more-interfaces-opattr">Operation Attributes</a><br> 5.4.2 <a href="#N67874">Operation Message References</a><br> 5.4.2.1 <a href="#N67903">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N67927">The element Attribute</a><br> 5.4.2.3 <a href="#N68008">Multiple infault or outfault Elements</a><br> 5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br> 6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br> 6.2 <a href="#more-bindings-reusable">Reusable Bindings</a><br> 6.3 <a href="#more-bindings-faults">Binding Faults</a><br> .4 <a href="#bindingOperations">Binding Operations</a><br> 6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 6.6.1 <a href="#N68453">Explanation of
! Example</a><br> 6.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br> 7.1 <a href="#adv-extensibility">Extensibility</a><br> 7.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 7.2 <a href="#adv-FP">Features and Properties</a><br> 7.2.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br> 7.2.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br> 7.2.3 <a href="#adv-fp-properties">Properties</a><br> 7.3 <a href="#adv-MEP">Defining New MEPs</a><br> 7.3.1 <a href="#challenge-confirm">Confirmed Challenge</a><br> 7.4 <a href="#adv-import-and-athoring">Import mechanism and authoring style</a><br> 7.5 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br> 7.6 <a href="#adv-versioning">Web Service Versioning</a><br> 7.6.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> 7.6.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 7.6.3 <a href="#ad-versioing-migration">Evolving a Service</a><br> 7.6.4 <a href="#adv-versioning-combined">Combined Approaches</a><br> 7.7 <a href="#adv-MTOM">MTOM Support</a><br> 7.8 <a href="#adv-RPCstyle">RPC Style</a><br> 7.9 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 7.10 <a href="#adv-service-refereces">Describing Web Service Messages That Refer to Other Web Services</a><br> 7.10.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br> 7.10.2 <a href="#reservationList">The Reservation List Web Service</a><br> 7.10.3 <a href="#reservationDetails_HTTP">Reservation Details Web Service Using HTTP Transfer</a><br> 7.10.4 <a href="#reservationList_HTTP_GET">Reservation List Web Service Using HTTP GET</a><br> 7.11 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br> 7.11.1 <a href="#N70042">Schemas in Imported Documents</a><br> 7.11.2 <a href="#N70181">Multiple Inline Schemas in One Document</a><br> 7.11.3 <a href="#adv-schema-locaton">The schemaLocation Attribute</a><br> 7.11.3.1 <a href="#N70277">Using the id Attribute to Identify Inline
Schemas</a><br> 7.12 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br> 7.12.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</a><br> 7.13 <a href="#adv-notes-on-uris">Notes on URIs</a><br> 7.13.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br> 7.13.2 <a href="#adv-relative-uris">Relative URIs</a><br> 7.13.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>8. <a href="#References">References</a><br> 8.1 <a href="#Normative-References">Normative References</a><br> 8.2 <a href="#Informative-References">Informative References</a><br></p>
<h3><a name="appendix" id="appendix">Appendix</a></h3><p class="toc">A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="body">
--- 97,101 ----
<h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br>A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="toc">
<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL 2.0 Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#bascs-interface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> &nbs;3.2 <a href="#wsdl-schema">WSDL 2.0 Schema and Element Ordering</a><br> 3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br> 4.1 <a href="#more-types-schema-inline">Inlining XML Schema</a><br> 4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br> 5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 5.3 <a href="#more-interfaces-faults">Interface Faults</a><br> 5.4 <a href="#more-interfaces-operations">Interface Operations</a><br> 5.4.1 <a href="#more-interfaces-opattr">Operation Attributes</a><br> 5.4.2 <a href="#N67874">Operation Message References</a><br> 5.4.2.1 <a href="#N67903">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N67927">The element Attribute</a><br> 5.4.2.3 <a href="#N68008">Multiple infault or outfault Elements</a><br> 5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br> 6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br> 6.2 <a href="#more-bindings-reusable">Reusable Bindings</a><br> 6.3 <a href="#more-bindings-faults">Binding Faults</a><br> .4 <a href="#bindingOperations">Binding Operations</a><br> 6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 6.6.1 <a href="#N68453">Explanation of
! Example</a><br> 6.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br> 7.1 <a href="#adv-extensibility">Extensibility</a><br> 7.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 7.2 <a href="#adv-FP">Features and Properties</a><br> 7.2.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br> 7.2.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br> 7.2.3 <a href="#adv-fp-properties">Properties</a><br> 7.3 <a href="#adv-MEP">Defining New MEPs</a><br> 7.3.1 <a href="#challenge-confirm">Confirmed Challenge</a><br> 7.4 <a href="#adv-import-and-athoring">Import mechanism and authoring style</a><br> 7.5 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br> 7.6 <a href="#adv-versioning">Web Service Versioning</a><br> 7.6.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> 7.6.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 7.6.3 <a href="#ad-versioing-migration">Evolving a Service</a><br> 7.6.4 <a href="#adv-versioning-combined">Combined Approaches</a><br> 7.7 <a href="#adv-MTOM">MTOM Support</a><br> 7.8 <a href="#adv-RPCstyle">RPC Style</a><br> 7.9 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 7.10 <a href="#adv-service-refereces">Describing Web Service Messages That Refer to Other Web Services</a><br> 7.10.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br> 7.10.2 <a href="#reservationList">The Reservation List Web Service</a><br> 7.10.3 <a href="#reservationDetails_HTTP">Reservation Details Web Service Using HTTP Transfer</a><br> 7.10.4 <a href="#reservationList_HTTP_GET">Reservation List Web Service Using HTTP GET</a><br> 7.11 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br> 7.11.1 <a href="#N70078">Schemas in Imported Documents</a><br> 7.11.2 <a href="#N70217">Multiple Inline Schemas in One Document</a><br> 7.11.3 <a href="#adv-schema-locaton">The schemaLocation Attribute</a><br> 7.11.3.1 <a href="#N70313">Using the id Attribute to Identify Inline
Schemas</a><br> 7.12 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br> 7.12.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</a><br> 7.13 <a href="#adv-notes-on-uris">Notes on URIs</a><br> 7.13.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br> 7.13.2 <a href="#adv-relative-uris">Relative URIs</a><br> 7.13.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>8. <a href="#References">References</a><br> 8.1 <a href="#Normative-References">Normative References</a><br> 8.2 <a href="#Informative-References">Informative References</a><br></p>
<h3><a name="appendix" id="appendix">Appendix</a></h3><p class="toc">A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="body">
***************
*** 1425,1429 ****
<div class="div2">
<h3><a name="adv-get-vs-post"></a>6.7 HTTP GET Versus POST: Which to Use?</h3>
! <p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <em>URIs, Addressability, and the use of HTTP GET and POST</em> ([<cite><a href="#TAG-whenToUseGET">W3C TAG Finding: Use of HTTP GET</a></cite>]). From the abstract:</p><p>"<em>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</em>"</p><p>Recall that the concept o a safe operation was discussed in <a href="#more-interfaces-op-attr"><b>5.4.1 Operation Attributes</b></a>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>wsdlx:safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><ul><li><p>If the WSDL 2.0 SOAP binding extension is used (<a href="#more-bindings-soap"><b>6.5 The SOAP Binding Extension</b></a>), with HTTP as the underlying transport protocol, then GET may be specified by setting:</p><dl><dt class="label"><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></dt><dd><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></dd><dt class="label"><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></dt><d><p>on the binding <code>operation</code> element, which causes GET to be used by default.</p></dd></dl><p> </p></li><li><p>If the WSDL 2.0 HTTP binding extension is used directly (<a href="#more-bindings-http"><b>6.6 The HTTP Binding Extension</b></a>), GET may be specified by setting either:</p><dl><dt class="label"><code>whttp:methodDefault="GET"</code></dt><dd><p>on the <code>binding</code> element; or</p></dd><dt class="label"><code>whttp:method="GET"</code></dt><dd><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element.</p></dd></dl><p></p></li></ul>
</div></div>
--- 1425,1461 ----
<div class="div2">
<h3><a name="adv-get-vs-post"></a>6.7 HTTP GET Versus POST: Which to Use?</h3>
! <p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <em>URIs, Addressability, and the use of HTTP GET and POST</em> ([<cite><a href="#TAG-whenToUseGET">W3C TAG Finding: Use of HTTP GET</a></cite>]). From the abstract:</p><p>"<em>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</em>"</p><p>Recall that the concept o a safe operation was discussed in <a href="#more-interfaces-op-attr"><b>5.4.1 Operation Attributes</b></a>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>wsdlx:safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p>
!
! <ul>
!
! <li><p>If the WSDL 2.0 SOAP binding extension is used (<a href="#more-bindings-soap"><b>6.5 The SOAP Binding Extension</b></a>), with HTTP as the underlying transport protocol, then GET may be specified by setting:</p><dl><dt class="label"><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></dt><dd><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></dd><dt class="label"><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></dt><dd><p>on the binding <code>operation</code> element, which causes GET to be used by default.</p></dd></dl><p> </p></li>
! <li><p>If the WSDL 2.0 HTTP binding extension is used directly (<a href="#more-bindings-http"><b>6.6 The HTTP Binding Extension</b></a>), GET may be specified by setting either:</p><dl><dt class="label"><code>whttp:methodDefault="GET"</code></dt><dd><p>on the <code>binding</code> element; or</p></dd><dt class="label"><code>whttp:method="GET"</code></dt><dd><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element; or </p></dd>
! <dt class="label"><code>wsdlx:safe="true" </code></dt><dd><p> on the bound <code>interface operation </code>. When the above two items are not explicitly set, and when the bound interface operation is marked safe, the HTTP Binding will by default set the method to GET.</p></dd>
!
! <p>For example, in the GreatH interface definition shown in <a href="#example-initial-interface">Example 2-4</a>, the wsdlx:safe attribute is set to "true". The HTTP binding definition in <a href="#example-bindings-http">Example 6-2</a> may take advantage of that and be simplified as below and still have the http method set to GET by default: </p>
!
! <div class="exampleOuter">
! <p style="text-align: left" class="exampleHead"><a name="example-binding-safety"></a><i><span>Example 6-4. </span>Safety and HTTP Binding</i></p>
!
! <div class="exampleInner"><pre>
! <?xml version="1.0" encoding="utf-8" ?>
!
! <binding name="reservationHTTPBinding"
!
! interface="tns:reservationInterface"
!
! type="http://www.w3.org/2005/05/wsdl/http" >
!
! <operation ref="tns:opCheckAvailability"
!
! whttp:location="{checkInDate}"/>
!
! </binding></pre></div>
! </div>
!
!
!
! </dl><p></p></li></ul>
!
</div></div>
***************
*** 2955,2959 ****
<div class="div3">
! <h4><a name="N70042"></a>7.11.1 Schemas in Imported Documents</h4>
<p>
In this example, we consider some GreatH Hotel
--- 2987,2991 ----
<div class="div3">
! <h4><a name="N70078"></a>7.11.1 Schemas in Imported Documents</h4>
<p>
In this example, we consider some GreatH Hotel
***************
*** 3162,3166 ****
<div class="div3">
! <h4><a name="N70181"></a>7.11.2 Multiple Inline Schemas in One Document</h4>
<p>
A WSDL 2.0 document may define multiple inline
--- 3194,3198 ----
<div class="div3">
! <h4><a name="N70217"></a>7.11.2 Multiple Inline Schemas in One Document</h4>
<p>
A WSDL 2.0 document may define multiple inline
***************
*** 3296,3300 ****
the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer (see [<cite><a href="#XPTR">XPointer Framework</a></cite>]) can also be used.
</p><div class="div4">
! <h5><a name="N70277"></a>7.11.3.1 Using the id Attribute to Identify Inline
Schemas</h5><p>
<a href="#schemaIds.wsdl">Example 7-29</a>
--- 3328,3332 ----
the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer (see [<cite><a href="#XPTR">XPointer Framework</a></cite>]) can also be used.
</p><div class="div4">
! <h5><a name="N70313"></a>7.11.3.1 Using the id Attribute to Identify Inline
Schemas</h5><p>
<a href="#schemaIds.wsdl">Example 7-29</a>
Received on Friday, 17 June 2005 21:47:00 UTC