WSDL 2.0 - interface
Jakob Jenkov |
The WSDL interface element describes the operations supported by your web service. Each operation
represents an interaction between the client and the service. In other words, the client can only call one operation
per request. Operations are thus very similar to methods / procedures in a programming language.
Here is an interface element example:
<interface name = "latestTutorialInterface" >
<fault name = "invalidDateFault" element = "stns:invalidDateError"/>
<operation name="latestTutorialOperation"
pattern="http://www.w3.org/ns/wsdl/in-out"
style="http://www.w3.org/ns/wsdl/style/iri"
wsdlx:safe = "true">
<input messageLabel="In" element="stns:latestTutorialRequest" />
<output messageLabel="Out" element="stns:latestTutorialResponse" />
<outfault messageLabel="Out" ref ="tns:invalidDateFault" />
</operation>
</interface>
Note, this code style="http://www.w3.org/ns/wsdl/style/iri" has been reported to cause some
validation problems with the above code. If you get them too, try to remove this line and try again.
I'll take you through the parts of the interface element in the rest of this text.
Interface Name
Since you can have more than one interface element in a WSDL 2.0 file, each interface must be given an unique name. This name is defined in the name attribute of the interface element, as shown here:
<interface name="latestTutorialInterface" >
Fault
The fault element defines a fault which can be sent back to the client. The same fault can
be used by multiple operations. That is why it is defined outside the following operation element. Here
is a fault element example:
<fault name = "invalidDateFault" element = "stns:invalidDateError"/>
The name attribute is used to give the fault a name. That name is used later in the operation
element to reference this fault.
The element attribute contains a reference to a fault element, defined in the types element,
earlier in the WSDL file.
The stns name space (Schema Target Name Space) points inside the XML Schema defined in
the types element. The invalidDateError is an
element defined inside that XML Schema. Hence the qualified reference stns:invalidDateError .
Operation
The operation element describes an operation. A method or procedure, in other words.
Here is an example:
<operation
name="latestTutorialOperation"
pattern="http://www.w3.org/ns/wsdl/in-out"
style="http://www.w3.org/ns/wsdl/style/iri"
wsdlx:safe = "true">
<input messageLabel="In" element="stns:latestTutorialRequest" />
<output messageLabel="Out" element="stns:latestTutorialResponse" />
<outfault messageLabel="Out" ref ="tns:invalidDateFault" />
</operation>
The name attribute of the operation element defines the name for the operation. This
name must be unique within the interface element. The operation name is
used later, when describing bindings for the operation.
The pattern attribute of the operation element describes what message exchange
pattern this operation uses. These can be either in, out or in-out, meaning data in, data out, data in-out.
Or, request-only, response-only, request-response. In-out is the most common pattern to use.
The style attribute is left out here.
The wsdlx:safe attribute indicates that this operation is safe to call, meaning
the customer does not agree to buy anything, or order anything.
The input element describes the expected input data for the operation.
The input element references an XML element defined in the types element
of the WSDL file.
The output element describes the data returned by the operation. The
output element references an XML element defined in the types
element of the WSDL file.
The outfault defines a possible output fault which can be sent to the client,
if the operation fails. The ref attribute references the fault
defined earlier in the interface element. The messageLabel attribute
is signaling which message the fault replaces.
| Tweet | |
Jakob Jenkov | |
