Re: Another try at HTTP binding

Philippe, is there any chance you could provide a diff over the 
existing spec text (or any other mechanism that you might deem 
appropriate), to make it easier to evaluate your proposed changes?

Jean-Jacques.

Philippe Le Hegaret wrote:

> 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, 8 January 2004 11:41:15 UTC