Another try at HTTP binding

Here is a revised proposal for the HTTP binding. It includes the general
URI replacement with an example. It also includes content duplication if
HTTP POST and General URI replacement mechanism are in use (as discussed
last week).

[[
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 element names and content MUST be URI escaped when inserted in the
 URI.

1.1 General URI replacement mechanism

 The URI 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". In order to apply the URI replacement
 mechanism, the Interface Operation component MUST follow the rules of
 one of the following operation styles: RPC style, Set-Attribute Style
 (only if the HTTP verb in use is POST or PUT), or Get-Attribute Style.
 
 The URI may also contain one or more patterns for each element of the
 sequence defined by the content model. Each pattern MUST reference one
 element using its qualified name and an element MUST NOT be referenced
 more than once using the URI replacement pattern. Each element MUST
 have 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.

 Note that elements referenced using the URI replacement patterns are
 NOT removed from the set of elements when using the HTTP POST and PUT
 bindings. Elements referenced using the URI replacement patterns are
 removed from the set of elements when using the HTTP GET and DELETE
 bindings.
 
  Example:

  Given the XML schema definition and operation component:
  <xs:element name="InputCarData">
    <xs:complexType>
      <xs:sequence">
        <xs:element name="license" type="xsd:NCName"/>
        <xs:element name="property" type="xsd:NMTOKEN"/>
      </xs:sequence">
    </xs:complexType>
  </xs:element>

  <interface name='Cars'>
   <operation name="getProperty_Input">
     <input message='my:InputCarData' />
     <input message='my:OutputCarData' />
   </operation>
  </interface>

  with the following instance message component:
   <my:InputCarData>
    <my:license>AAA555</my:license>
    <property>color</property>
   </my:InputCarData>
   
  The URL of the endpoint is
    http://motorvehicles.example.com/cars
  
  The binding location of the interface operation component is
   location='/{my:license}/{my:property}'
   

  Using the URI 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

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. As defined by the RFC
 2616 (Section 9), the operation MUST be safe and idempotent. 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).

 Once the general URI replacement has been applied, the remaning
 elements are encoded as query parameters in the URI of the HTTP GET
 request. The body of the HTTP GET request is empty.

 In order to apply the URI replacement mechanism, the Interface
 Operation component MUST follow the rules of one of the following
 operation styles: RPC style or Get-Attribute Style.

 The local names of the remaining elements MUST be unique, independently
 of their associated namespaces.

1.2.1 No remaining elements

 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 remaining elements

  Each remaining element MUST have an XML Schema type that is derived
  from xsd:anySimpleType with the exception of the types xsd:hexBinary
  and xsd:base64Binary.

  This HTTP GET binding is NOT applicable if one of the elements
  references the following XML Schema types:
  - 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 element binds to one or more pairs of [name, value]. Pairs are
  inserted in the query part of the URL. The [local name] property of
  the element information item represents the name in the pair.
  
  Unless the XML Schema type is a list simple type definition, the
  element binds to exactly one pair of [name, value] and the value
  associated with the name is the content of the instance input message.

  Example:

  <xs:element name="InputCarData">
    <xs:complexType>
      <xs:sequence">
        <xs:element name="license" type="xsd:NCName"/>
        <xs:element name="property" type="xsd:NMTOKEN"/>
      </xs:sequence">
    </xs:complexType>
  </xs:element>

  <interface name='Cars'>
   <operation name="getProperty_Input">
     <input message='my:InputCarData' />
     <input message='my:OutputCarData' />
   </operation>
  </interface>

  with the following instance message component:
   <my:InputCarData>
    <my:license>AAA555</my:license>
    <property>color</property>
   </my:InputCarData>
   
  The URI of the endpoint is
    http://motorvehicles.example.com/cars/
  
  The binding location of the interface operation component is
   location='{my:license}'
   
  Using the URI replacement mechanism, the license is inserted into the
  URI
    http://motorvehicles.example.com/cars/AAA555

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

  If the element has an XML Schema list simple type definition, each item
  in the content of the instance element 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:


  <xs:element name="InputCarData">
    <xs:complexType>
      <xs:sequence">
        <xs:element name="license" type="xsd:NCName"/>
        <xs:element name="properties" type="xsd:NMTOKENS"/>
      </xs:sequence">
    </xs:complexType>
  </xs:element>

  <interface name='Cars'>
   <operation name="getProperty_Input">
     <input message='my:InputCarData' />
     <input message='my:OutputCarData' />
   </operation>
  </interface>

  with the following instance message component:
   <my:InputCarData>
    <my:license>AAA555</my:license>
    <properties>color year engine_number</properties>
   </my:InputCarData>
   
  The URI of the endpoint is
    http://motorvehicles.example.com/cars/
  
  The binding location of the interface operation component is
   location='{my:license}'
   
  Using the URI replacement mechanism, the license is inserted into the
  URI
    http://motorvehicles.example.com/cars/AAA555

  Using the URI 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 MAY have side
 effect on the resource identified by a URI. The operation is NOT
 guaranteed to be safe and idempotent, as suggested by the RFC
 2616.

 The elements of the input are encoded in the body of the HTTP POST
 request. Note that all elements that have been included in the URI
 using the general URI replacement mechanism are included as well in the
 body of the HTTP POST request.

1.3.1 Using the XML encoding mechanism

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

 The element referenced from the input component of the interface
 operation component is the content of the body of the HTTP POST
 request.

 Example:

  @@TODO

1.3.2 Using the multipart encoding mechanism

  Each element of the sequence inside the element referenced from the
  input component of the interface operation component is encoded as a
  separate multipart part. In order to apply this mechanism, the
  Interface Operation component MUST follow the rules of one of the
  following operation styles: RPC style, or Set-Attribute Style.

  For each element in the sequence:
 
  - If the element has a simple type definition xsd:hexBinary or
  xsd:base64Binary or a derived type from xsd:hexBinary or
  xsd:base64Binary, the content of the element instance is the content
  and the media type is the one specified (@@cf Media types work).

  - Otherwise, the XML representation of the element instance is the
  content and the media type is application/xml or any derived XML type
  (*/*+xml).

  Example:

   @@TODO

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

  Each element of the sequence referenced from the interface operation
  MUST have an XML Schema type that is derived from xsd:anySimpleType
  with the exception of the types xsd:hexBinary and xsd:base64Binary.

  This mechanism is NOT 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]
]]

Philippe

Received on Thursday, 18 December 2003 10:56:41 UTC