HTTP GET & POST Binding

HTTP GET & POST Binding

WSDL includes a binding for HTTP 1.1's GET and POST verbs in order to describe the interaction between a Web Browser and a web site. This allows applications other than Web Browsers to interact with the site. The following protocol specific information may be specified:

• An indication that a binding uses HTTP GET or POST
• An address for the port
• A relative address for each operation (relative to the base address defined by the port)

4.1 HTTP GET/POST Examples

The following example shows three ports that are bound differently for a given port type.

If the values being passed are part1=1, part2=2, part3=3, the request format would be as follows for each port:

port1: GET, URL="http://example.com/o1/A1B2/3"

port2: GET, URL="http://example.com/o1?p1=1&p2=2&p3=3

port3: POST, URL="http://example.com/o1", PAYLOAD="p1=1&p2=2&p3=3"

For each port, the response is either a GIF or a JPEG image.

Example 6. GET and FORM POST returning GIF or JPG

<definitions .... >

<message name="m1">

<part name="part1" type="xsd:string"/>

<part name="part2" type="xsd:int"/>

<part name="part3" type="xsd:string"/>

</message>

<message name="m2">

<part name="image" type="xsd:binary"/>

</message>

<portType name="pt1">

<operation name="o1">

<input message="tns:m1"/>

<output message="tns:m2"/>

</operation>

</portType>

<service name="service1">

<port name="port1" binding="tns:b1">

<http:address location="http://example.com/"/>

</port>

<port name="port2" binding="tns:b2">

<http:address location="http://example.com/"/>

</port>

<port name="port3" binding="tns:b3">

<http:address location="http://example.com/"/>

</port>

</service>

<binding name="b1" type="pt1">

<http:binding verb="GET"/>

<operation name="o1">

<http:operation location="o1/A(part1)B(part2)/(part3)"/>

<input>

<http:urlReplacement/>

</input>

<output>

<mime:content type="image/gif"/>

<mime:content type="image/jpeg"/>

</output>

</operation>

</binding>

<binding name="b2" type="pt1">

<http:binding verb="GET"/>

<operation name="o1">

<http:operation location="o1"/>

<input>

<http:urlEncoded/>

</input>

<output>

<mime:content type="image/gif"/>

<mime:content type="image/jpeg"/>

</output>

</operation>

</binding>

<binding name="b3" type="pt1">

<http:binding verb="POST"/>

<operation name="o1">

<http:operation location="o1"/>

<input>

<mime:content type="application/x-www-form-urlencoded"/>

</input>

<output>

<mime:content type="image/gif"/>

<mime:content type="image/jpeg"/>

</output>

</operation>

</binding>

</definitions>

4.2 How the HTTP GET/POST Binding Extends WSDL

The HTTP GET/POST Binding extends WSDL with the following extension elements:

<definitions .... >

<binding .... >

<http:binding verb="nmtoken"/>

<operation .... >

<http:operation location="uri"/>

<input .... >

<-- mime elements -->

</input>

<output .... >

<-- mime elements -->

</output>

</operation>

</binding>

<port .... >

<http:address location="uri"/>

</port>

</definitions>

These elements are covered in the subsequent sections.

4.3 http:address

The location attribute specifies the base URI for the port. The value of the attribute is combined with the values of the location attribute of the http:operation binding element. See section 4.5 for more details.

4.4 http:binding

The http:binding element indicates that this binding uses the HTTP protocol.

<definitions .... >

<binding .... >

<http:binding verb="nmtoken"/>

</binding>

</definitions>

The value of the required verb attribute indicates the HTTP verb. Common values are GET or POST, but others may be used. Note that HTTP verbs are case sensitive.

4.5 http:operation

The location attribute specifies a relative URI for the operation. This URI is combined with the URI specified in the http:address element to form the full URI for the HTTP request. The URI value MUST be a relative URI.

<definitions .... >

<binding .... >

<operation .... >

<http:operation location="uri"/>

</operation>

</binding>

</definitions>

4.6 http:urlEncoded

The urlEncoded element indicates that all the message parts are encoded into the HTTP request URI using the standard URI-encoding rules (name1=value&name2=value…). The names of the parameters correspond to the names of the message parts. Each value contributed by the part is encoded using a name=value pair. This may be used with GET to specify URL encoding, or with POST to specify a FORM-POST. For GET, the "?" character is automatically appended as necessary.

<http:urlEncoded/>

For more information on the rules for URI-encoding parameters, see [5], [6], and [7].

4.7 http:urlReplacement

The http:urlReplacement element indicates that all the message parts are encoded into the HTTP request URI using a replacement algorithm:

• The relative URI value of http:operation is searched for a set of search patterns.
• The search occurs before the value of the http:operation is combined with the value of the location attribute from http:address.
• There is one search pattern for each message part. The search pattern string is the name of the message part surrounded with parenthesis "(" and ")".
• For each match, the value of the corresponding message part is substituted for the match at the location of the match.
• Matches are performed before any values are replaced (replaced values do not trigger additional matches).

Message parts MUST NOT have repeating values.

<http:urlReplacement/>