HTTP binding for WSDL 1.2

This proposal does no take into account (yet) the following messages:
http://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0059.html
http://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0028.html
http://lists.w3.org/Archives/Public/public-ws-pnf-tf/2003Mar/0025.html

I did not propose a syntax but I'll happy to decorate any XML tree
later, depending on the review from the WG.

It would be good to include some guidelines on how to map an operation
to the Web at some point. Not sure if it has to be part of the
specification or in a separate document (Note?).

Philippe

1 HTTP binding for input message reference components referencing XML
  Schema types

 If two operations happen to have the same input, only one is allowed
 to be bound to get.

 [[need better wording to express this constraint in terms of
 components. This constraint should probably be applied from the
 endpoint component level]]

 All Part Components names and values MUST be URI escaped when inserted
 in the URI.

1.1 Part Component replacement mechanism

 The Part Component replacement mechanism can be applied to the HTTP
 binding, independently of the HTTP method in use. The replacement
 property contains a relative URI, without a query part and this URI is
 relative to the "service endpoint".
 
 The URI may also contain one or more part component replacement
 patterns. Each pattern MUST reference one part component using its name
 property and a part component MUST NOT be referenced more than once
 using the part component replacement pattern. Each {content references}
 referenced from the part component MUST reference an XML Schema type
 that is derived from xsd:anySimpleType with the exception of the types
 xsd:hexBinary, xsd:base64Binary, and a list simple type.

 All part components referenced using part component replacement
 patterns are removed from the set of part components considered during
 the HTTP GET or HTTP POST bindings.
 
  Example:

  Given the message component:
  <message name="getProperty_Input">
    <part name="license" type="xsd:NCName"/>
    <part name="property" type="xsd:NMTOKEN"/>
  </message>

  with the following instance message component:
   license is "AAA555"
   property is "color"

  The URL of the endpoint is
    http://motorvehicles.example.com/
  
  Using the Part Component replacement mechanism, a new relative URI is
  computed and the license and property parts are inserted into the URL
   http://motorvehicles.example.com/cars/AAA555/color

  The HTTP GET binding is then use. Given that all part components are
  already consumed by the Part Component replacement mechanism, there is
  no more part component to be taken into account and section 1.2.1
  applies. Therefore, the URL used for the HTTP GET Request is:
   http://motorvehicles.example.com/cars/AAA555/color

1.2 HTTP GET binding

 The HTTP GET binding SHOULD be used for operations that retrieve a
 representation of a resource identified by a URL. The output of the
 operation should be cachable. Invoking the operation two or more times
 should have the same affect on the server as invoking it once. Input
 parameters SHOULD be used to filter the content of the representation,
 for example to performs searches or queries. Operations that do not
 satisfy these requirements SHOULD use the POST binding (or other
 application HTTP verbs when bindings for them are specified).

 The Part Components of the input message are encoded in the URL of the
 HTTP GET request.

1.2.1 No Part Component

 In such case, no query parameters are required to be sent to the
 resource. The URL used for the HTTP GET request is equivalent to the
 one composed from section 1.1.

 Example:
  URL used for the HTTP GET request:
   http://motorvehicles.example.com/cars/AAA555/color

1.2.2 One or more Part Components

  Each {content reference} referenced from the part components MUST
  reference an XML Schema type that is derived from xsd:anySimpleType
  with the exception of the types xsd:hexBinary and xsd:base64Binary.

  The URL encoding mechanism MUST NOT be used applicable if one of the
  types referenced from the message parts reference:
  - an XML Schema complex type definition
  - the XML Schema types xsd:hexBinary and xsd:base64Binary, a type
  derived from xsd:hexBinary or xsd:base64Binary.

  Each part component binds to one or more pairs of [name, value]. Pairs
  are inserted in the query part of the URL. The {name} property
  represents the name in the pair.
  
  Unless the XML Schema type is a list simple type definition, the part
  component binds to exactly one pair of [name, value] and the value
  associated with the name is the content of the instance part
  component.

  Example:

  Given the message component:
  <message name="getProperty_Input">
    <part name="license" type="xsd:NCName"/>
    <part name="property" type="xsd:NMTOKEN"/>
  </message>

  with the following instance message component:
   license is "AAA555"
   property is "color"

  The URL of the endpoint is
    http://motorvehicles.example.com/
  
  Using the Part Component replacement mechanism, the license is
  inserted into the URL
    http://motorvehicles.example.com/AAA555

  Using the URL encoding mechanism, the property is added in the query
  part:
   http://motorvehicles.example.com/AAA555?property=color

  If the {content reference} is a list simple type definition, each item
  in the content of the instance part component binds to a pair, and the
  values are the items themselves (the name remains the same for all
  pairs). Note that if the list is empty, no pair will be created.

  Example:

  Given the message component:
  <message name="getProperty_Input">
    <part name="license" type="xsd:NCName"/>
    <part name="properties" type="xsd:NMTOKENS"/>
  </message>

  with the following instance message component:
  license is "AAA555"
  properties is "color year engine_number"

  The URL of the endpoint is
    http://motorvehicles.example.com/
  
  Using the Part Component replacement mechanism, the license is
  inserted into the URL
    http://motorvehicles.example.com/AAA555

  Using the URL encoding mechanism, the properties are added in the
query
  part:
  
http://motorvehicles.example.com/AAA555?properties=color&properties=year&properties=engine_number

1.3 HTTP POST binding

 The HTTP POST binding SHOULD be used for operations that have side
 effect a representation of a resource identified by a URL. The output
 of the operation should be cachable. Invoking the operation two or more
 times should have the same affect on the server as invoking it
 once. Input parameters SHOULD be used to filter the content of the
 representation, for example to performs searches or queries. Operations
 that do not satisfy these requirements SHOULD use the POST binding (or
 other application HTTP verbs when bindings for them are specified).

 The Part Components of the input message are encoded in the content of
 the HTTP POST request.

1.3.1 No Part Component

 The content of the request is also empty and the HTTP header
 Content-Length MUST have a value of 0 (zero). The URL used for the
 HTTP GET request is equivalent to the one composed from section 1.1.

 Example:
  URL used for the HTTP POST request:
   http://motorvehicles.example.com/cars/AAA555/color

1.3.2 One or more Part Components

1.3.2.1 Using the XML encoding mechanism

 The HTTP header Content-Type must be the media type application/xml or
 any derived XML type (*/*+xml).

1.3.2.1.1 The message component contains exactly one Part Component

 If the {content reference} is an element type definition, the XML
 representation of the element instance is the content.  Otherwise, a
 wrapper element is created using the {local name} and {namespace name}
 property of the interface operation component. The instance of the part
 component is then attached to the wrapper element. The XML
 representation of the result is the content.

 Example:

  targetNamespace: http://www.example.com/ex

  <message name="setProperty_Input">
    <part name="license"  type="xsd:NCName"/>
    <part name="property" type="xsd:NMTOKEN"/>
    <part name="value"    type="xsd:NMTOKEN"/>
  </message>

  <operation name="setProperty">
    <input message="x:setProperty_Input" />
  </message>

  with the following instance message component:
   license is "AAA555"
   property is "color"
   value    is "red"

  The URL of the endpoint is
    http://motorvehicles.example.com/
  
  Using the Part Component replacement mechanism, the license and
  property are inserted into the URL
   http://motorvehicles.example.com/AAA555/color

  The HTTP POST request then becomes:

  POST http://motorvehicles.example.com/AAA555/color HTTP/1.1
  Host: motorvehicles.example.com
  Content-Type: application/xml
  Content-Length: 65

  <setProperty xmlns='http://www.example.com/ex'>red</setProperty>

  @@what about the xsi:type attribute ?
   
1.3.2.1.2 The message component contains at least two Part Components

 A global wrapper element is created using the {local name} and
 {namespace name} property of the interface operation component. For
 each part component:

 - if the {content reference} is an element type definition, the element
 instance is being appended as a child of the global wrapper element.

 - otherwise, a wrapper element is created using the {local name} and
 {namespace name} property of the part component. The instance of the
 part component is then attached to this wrapper element. The wrapper
 element is being appended as a child of the global wrapper element.

 The XML representation of the result global wrapper element is the
 content.

 Example:

  @@TODO

1.3.2.2 Using the multipart encoding mechanism

  Each part component is encoded as a separate multipart part.

  If the {content reference} is an element type definition, the XML
  representation of the element instance is the content and the media
  type is application/xml or any derived XML type (*/*+xml).

  If the {content reference} is the simple type definition xsd:hexBinary
  or xsd:base64Binary or a derived type from xsd:hexBinary or
  xsd:base64Binary, the content of the instance part component is the
  content and the media type is the one specified (@@see Arthur's
  proposal and upcoming plh's proposal).

  Otherwise, a wrapper element is created using the {local name} and
  {namespace name} property of the part component. The instance of the
  part component is then attached to this wrapper element. The XML
  representation of the result is the content and the media type is is
  application/xml.

  Example:

   @@TODO

1.3.2.3 Using the application/x-www-form-urlencoded encoding mechanism

  Each {content reference} referenced from the part components MUST
  reference an XML Schema type that is derived from xsd:anySimpleType
  with the exception of the types xsd:hexBinary and xsd:base64Binary.

  The URL encoding mechanism MUST NOT be used applicable if one of the
  types referenced from the message parts reference:
  - an XML Schema complex type definition
  - the XML Schema types xsd:hexBinary and xsd:base64Binary, a type
  derived from xsd:hexBinary or xsd:base64Binary.

  [[@@ describe the encoding mechanism or provide a reference to the
  right place]]

  Example:

   @@TODO

1.4 HTTP PUT binding

  @@TODO

  @@restriction on the output message?

1.5 HTTP DELETE binding

  @@TODO
  
  @@restriction on the output message?

2 HTTP binding for output message reference components referencing XML
  Schema types

 The content of the output message is encoded in the content of the HTTP
 reply.

 [ditto HTTP POST binding for input message, minus the URI mechanisms]

Received on Friday, 28 March 2003 09:11:10 UTC