MIME Binding

MIME Binding

WSDL includes a way to bind abstract types to concrete messages in some MIME format. Bindings for the following MIME types are defined:

• multipart/related
• text/xml
• application/x-www-form-urlencoded (the format used to submit a form in HTML)
• Others (by specifying the MIME type string)

The set of defined MIME types is both large and evolving, so it is not a goal for WSDL to exhaustively define XML grammar for each MIME type. Nothing precludes additional grammar to be added to define additional MIME types as necessary. If a MIME type string is sufficient to describe the content, the mime element defined below can be used.

5.11 MIME Binding example

Example 7. Using multipart/related with SOAP

This example describes that a GetCompanyInfo SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding. The request takes a ticker symbol of type string. The response contains multiple parts encoded in the MIME format multipart/related: a SOAP Envelope containing the current stock price as a float, zero or more marketing literature documents in HTML format, and an optional company logo in either GIF or JPEG format.

<definitions .... >

<types>

<schema .... >

<element name="GetCompanyInfo">

<complexType>

<all>

<element name="tickerSymbol " type="string"/>

</all>

</complexType>

</element>

<element name="GetCompanyInfoResult">

<complexType>

<all>

<element name="result" type="float"/>

</all>

</complexType>

</element>

<complexType name="ArrayOfBinary">

<complexContent>

<restriction base="soapenc:Array">

<attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:binary[]"/>

</restriction>

<complexContent>

</complexType>

</schema>

</types>

<message name="m1">

<part name="body" element="tns:GetCompanyInfo"/>

</message>

<message name="m2">

<part name="body" element="tns:GetCompanyInfoResult"/>

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

<part name="logo" type="tns:ArrayOfBinary"/>

</message>

<portType name="pt1">

<operation name="GetCompanyInfo">

<input message="m1"/>

<output message="m2"/>

</operation>

</portType>

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

<operation name="GetCompanyInfo">

<soap:operation soapAction="http://example.com/GetCompanyInfo"/>

<input>

<soap:body use="literal"/>

</input>

<output>

<mime:multipartRelated>

<mime:part>

<soap:body parts="body" use="literal"/>

</mime:part>

<mime:part>

<mime:content part="docs" type="text/html"/>

</mime:part>

<mime:part>

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

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

</mime:part>

</mime:multipartRelated>

</output>

</operation>

</binding>

<service name="CompanyInfoService">

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

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

</port>

</service>

</definitions>

5.2 How the MIME Binding extends WSDL

The MIME Binding extends WSDL with the following extension elements:

<mime:content part="nmtoken"? type="string"?/>

<mime:multipartRelated>

<mime:part> *

<-- mime element -->

</mime:part>

</mime:multipartRelated>

<mime:mimeXml part="nmtoken"?/>

They are used at the following locations in WSDL:

<definitions .... >

<binding .... >

<operation .... >

<input .... >

<-- mime elements -->

</input>

<output .... >

<-- mime elements -->

</output>

</operation>

</binding>

</definitions>

MIME elements appear under input and output to specify the MIME format. If multiple appear, they are considered to be alternatives.

5.3 mime:content

To avoid having to define a new element for every MIME format, the mime:content element may be used if there is no additional information to convey about the format other than its MIME type string.

<mime:content part="nmtoken"? type="string"?/>

The part attribute is used to specify the name of the message part. If the message has a single part, then the part attribute is optional. The type attribute contains the MIME type string. A type value has two portions, separated by a slash (/), either of which may be a wildcard (*). Not specifying the type attribute indicates that all MIME types are acceptable.

If the return format is XML, but the schema is not known ahead of time, the generic mime element can be used indicating text/xml:

<mime:content type="text/xml"/>

A wildcard (*) can be used to specify a family of mime types, for example all text types.

<mime:content type="text/*"/>

The following two examples both specify all mime types:

<mime:content type="*/*"/>

<mime:content/>

5.4 mime:multipartRelated

The multipart/related MIME type aggregates an arbitrary set of MIME formatted parts into one message using the MIME type "multipart/related". The mime:multipartRelated element describes the concrete format of such a message:

<mime:multipartRelated>

<mime:part> *

<-- mime element -->

</mime:part>

</mime:multipartRelated>

The mime:part element describes each part of a multipart/related message. MIME elements appear within mime:part to specify the concrete MIME type for the part. If more than one MIME element appears inside a mime:part, they are alternatives.

5.5 soap:body

When using the MIME binding with SOAP requests, it is legal to use the soap:body element as a MIME element. It indicates the content type is "text/xml", and there is an enclosing SOAP Envelope.

5.6 mime:mimeXml

To specify XML payloads that are not SOAP compliant (do not have a SOAP Envelope), but do have a particular schema, the mime:mimeXml element may be used to specify that concrete schema. The part attribute refers to a message part defining the concrete schema of the root XML element. The part attribute MAY be omitted if the message has only a single part. The part references a concrete schema using the element attribute for simple parts or type attribute for composite parts (see section 2.3.1).

<mime:mimeXml part="nmtoken"?/>

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/>