Status of this Document
This section describes the status of this document at the time
of its publication. Other documents may supersede this document.
A list of current W3C publications and the latest revision of
this technical report can be found in the
W3C technical reports index
at http://www.w3.org/TR/.
This is the 13 December 2011 Recommendation of the Web Services Transfer (WS-Transfer) specification.
It has been produced by the
Web
Services Resource Access Working Group (WG), which is part of the
W3C Web Services
Activity.
The public is encouraged to send comments to the Working Group's public mailing list
[email protected]
mailing list (public
archive). See W3C mailing list and archive usage guidelines.
No substantive changes were made as a result of the Proposed Recommendation phase (see also diff, test scenario and implementation report).
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
This document was produced by a group operating under the
5
February 2004 W3C Patent Policy. W3C maintains a
public
list of any patent disclosures made in connection with the
deliverables of the group; that page also includes instructions for
disclosing a patent. An individual who has actual knowledge of a
patent which the individual believes contains
Essential
Claim(s) must disclose the information in accordance with
section
6 of the W3C Patent Policy.
1 Composable Architecture
By using the XML, SOAP [SOAP11],
[SOAP12], and WSDL [WSDL11]
extensibility models, the Web service
specifications (WS-*) are designed to be composed with each other
to provide a rich set of tools for the Web
services environment. This specification specifically relies on
other Web service specifications to provide secure, reliable,
and/or transacted message delivery and to express Web service and
client policy.
2 Introduction
This specification defines a mechanism for acquiring XML-based
representations of entities using the Web service infrastructure.
It defines two types of entities:
Resources, which are entities addressable by an endpoint
reference that provide an XML representation
Resource factories, which are Web services that can create new
resources
Specifically, it defines two operations for sending and receiving the
representation of a given resource and two operations for creating and
deleting a resource and its corresponding representation.
Note that the state maintenance of a resource is at most
subject to the "best efforts" of the hosting server. When a client
receives the server's acceptance of a request to create or update a
resource, it can reasonably expect that the resource now exists at
the confirmed location and with the confirmed representation, but this
is not a guarantee, even in the absence of any third parties. The
server MAY change the representation of a resource, MAY remove a
resource entirely, or MAY bring back a resource that was deleted.
For instance, the server might store resource state information on a
disk drive. If that drive crashes and the server recovers state
information from a backup tape, changes that occurred after the
backup was made will be lost.
A server might have other operational processes that change resource
state information. For example, a server could purge resources that
have not been accessed for some period of time.
In addition to this, there might be application or process specific
reasons for a server to augment or transform the representation
provided by an update or create operation. For example, the server
might populate the optional properties of a newly created resource
with meaningful default values.
Finally all clients need to be aware that there might be other clients
simultaneously accessing, creating, and updating the same resources.
In essence, the confirmation by a service of having processed a
request to create, modify, or delete a resource implies a commitment
only at the instant that the confirmation was generated. While the
usual case is that resources are long-lived and stable, there are no
guarantees, and clients are advised to code defensively.
There is no requirement for uniformity in resource representations
between the messages defined in this specification. For example, the
representations used by Create or Put can differ from the representation
returned by Get, depending on the semantic requirements of the service.
Additionally, there is no requirement that the resource content is
fixed for any given endpoint reference. The resource content can vary
based on environmental factors, such as the security context, time
of day, configuration, or the dynamic state of the service.
2.1 Requirements
This specification intends to meet the following requirements:
3 Terminology and Notation
3.1 Notational Conventions
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in RFC 2119
[RFC 2119].
This specification uses the following syntax to define outlines for
messages:
The syntax appears as an XML instance, but values in italics
indicate data types instead of literal values.
Characters are appended to elements and attributes to indicate
cardinality:
"?" (0 or 1)
"*" (0 or more)
"+" (1 or more)
The character "|" is used to indicate a choice between
alternatives.
The characters "(" and ")" are used to
indicate that contained items are to be treated as a group with
respect to cardinality or choice.
The characters "[" and "]" are used to call
out references and property names.
Ellipsis (i.e. "...") indicate points of extensibility.
XML namespace prefixes (see Table 3-1) are used
to indicate the namespace of the element being defined.
In addition to Message Information Header properties
[WS-Addressing],
this specification uses the following properties to define messages:
- [Headers]
Unordered message headers.
- [Action]
The value to be used for the wsa:Action IRI.
- [Body]
A message body.
These properties bind to a SOAP Envelope as follows:
<s:Envelope>
<s:Header>
[Headers]
<wsa:Action>[Action]</wsa:Action>
...
</s:Header>
<s:Body>[Body]</s:Body>
</s:Envelope>
This specification can be used in terms of XML Information Set (Infoset)
[XML Infoset], even though the specification uses XML 1.0
terminology. Valid Infoset for this specification is the one
serializable in XML 1.0, hence the use of XML 1.0.
The term "generate" is used in relation to the various faults defined
by this specification to imply that a fault is produced and no
further processing SHOULD be performed. In these cases the fault
SHOULD be transmitted. However, there might be reasons when a compliant
implementation can choose not to transmit the fault - for example,
security concerns - in these situations the service MAY choose
not to transmit the fault.
3.2 Considerations on the Use of Extensibility Points
The elements defined in this specification MAY be extended at the
points indicated by their outlines and schema. Implementations MAY
add child elements and/or attributes at the indicated extension
points but MUST NOT contradict the semantics of the parent and/or
owner, respectively. If a receiver does not recognize an extension,
the receiver SHOULD ignore that extension. Senders MAY indicate
the presence of an extension that has to be understood through the use
of a corresponding SOAP Header with a soap:mustUnderstand attribute
with the value "1".
In cases where it is either desirable or necessary for the receiver
of a request that has been extended to indicate that it has
recognized and accepted the semantics associated with that extension,
it is RECOMMENDED that the receiver add a corresponding extension
to the response message. The definition of an extension SHOULD clearly
specify how the extension that appears in the response correlates
with that in the corresponding request.
Extension elements and attributes MUST NOT use the Web Services
Transfer namespace URI.
3.3 Terminology
- Resource
A Web service that is addressable using an endpoint reference
and can be represented by an XML Information Set.
The resource's representation MUST be representable by either zero or
one Document Information items. The following Information items MUST
NOT appear as children anywhere within the Document Information item's
children: Processing Instruction, Unexpanded Entity Reference, Document
Type Declaration, Unparsed Entity and Notation. The representation
of the resource can be in any XML version supported by the resource
manager, however, when transmitted within a SOAP Envelope the entire
envelope (including the representation of the resource) MUST use
the same XML version.
The representation can be retrieved using the Get operation
and can be manipulated using the Put and Delete operations.
- Resource Factory
A Web service that is capable of creating new resources using the
Create operation defined in this specification.
3.4 Compliance
An implementation is not compliant with this specification if it fails to
satisfy one or more of the MUST or REQUIRED level requirements defined
herein. A SOAP Node MUST NOT use the XML namespace identifier for this
specification (listed in 3.5 XML Namespaces) within SOAP
Envelopes unless it is compliant with this specification.
Normative text within this specification takes precedence over the XML
Schema and WSDL descriptions, which in turn take precedence over outlines,
which in turn take precedence over examples.
All messages defined by this specification MUST conform to the
WS-Addressing specifications and be sent to a Web service that
is addressable by an EPR (see [WS-Addressing]).
Unless otherwise noted, all IRIs are absolute IRIs and IRI comparison
MUST be performed according to [RFC 3987] section 5.3.1.
For any message defined by this specification, any OPTIONAL elements
or attributes in the message MAY be used by senders of the message;
however receivers of those messages MUST support those OPTIONAL
elements and attributes, unless other behavior is explicitly defined
by this specification.
Implementations are expected to support both UTF-8 and UTF-16 as
described in XML 1.0.
Implementations of this specification MUST conform to the corrected
version of WSDL as defined by the 'WSDL Correction' sections of WS-I
Basic Profile 1.2 [BP12] and WS-I Basic Profile 2.0
[BP20].
3.5 XML Namespaces
The XML Namespace URI that MUST be used by implementations of this
specification is:
Table 3-1 lists XML namespaces that are
used in this specification. The
choice of any namespace prefix is arbitrary and not semantically
significant.
The working group intends to update the value of the Web Services
Transfer namespace URI each time a new version of this document is
published until such time that the document reaches Candidate
Recommendation status. Once it has reached Candidate Recommendation
status, the working group intends to maintain the value of the
Web Services Transfer namespace URI that was assigned in the
Candidate Recommendation unless significant changes are made that
impact the implementation or break post-CR implementations of the
specification. Also see
http://www.w3.org/2001/tag/doc/namespaceState.html
and
http://www.w3.org/2005/07/13-nsuri
.
4 Resource Operations
4.1 Get
This specification defines one Web service operation (Get) for
fetching a one-time snapshot of the representation of a resource.
This operation MUST be supported by compliant WS-Transfer resources.
The Get request message MUST be of the following form:
[Action]
http://www.w3.org/2011/03/ws-tra/Get
[Body]
<wst:Get Dialect="xs:anyURI"? ...>
xs:any*
</wst:Get>
The following describes additional, normative constraints on the
outline listed above:
- [Body]/wst:Get
This is a REQUIRED element that has no defined child element
content.
- [Body]/wst:Get@Dialect
When this OPTIONAL attribute is present it contains a IRI that
refers to additional information for the service on how to
process this element. If the attribute is present but the
dialect IRI is not known then the service MUST generate an
wst:UnknownDialect fault. There is no default value for the
attribute. If the attribute is absent, then the base
behavior is used.
- [Body]/wst:Get@Dialect="http://www.w3.org/2011/03/ws-fra"
The WS-Fragment [WS-Fragment] specification defines
this dialect IRI. Use of this IRI indicates that the contents
of the Get element MUST be processed as specified by the
WS-Fragment [WS-Fragment] specification.
If the request message reaches a conformant implementation of
WS-Transfer and the message refers to an unknown resource, then the
implementation MUST generate a wst:UnknownResource fault.
A Get request MUST be targeted at the resource whose representation is
desired as described in 3 Terminology and Notation of
this specification.
If the resource accepts a Get request, it MUST reply with a response
of the following form:
[Action]
http://www.w3.org/2011/03/ws-tra/GetResponse
[Body]
<wst:GetResponse ...>
<wst:Representation ...>
xs:any?
</wst:Representation>?
xs:any*
</wst:GetResponse>
The following describes additional, normative constraints on the
outline listed above:
- [Body]/wst:GetResponse/wst:Representation
This OPTIONAL element acts as a container for the
full representation of
the resource. This element MUST be present if the corresponding
Get request did not specify a Dialect attribute. This element
MAY have no children in cases where there is no resource
representation.
Other components of the outline above are not further constrained
by this specification.
This operation is safe; it will not result in any side effect
imputable to the requester. This means that in case of an underlying
protocol error that might get unnoticed, resending the same request
can be done automatically.
The following shows a sample SOAP envelope containing a Get
request:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam123.example.org/pullport
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.org/repository</wsa:To>
<xxx:CustomerID wsa:IsReferenceParameter="true">
732199
</xxx:CustomerID>
<xxx:Region wsa:IsReferenceParameter="true">
EMEA
</xxx:Region>
<wsa:Action>
http://www.w3.org/2011/03/ws-tra/Get
</wsa:Action>
<wsa:MessageID>
urn:uuid:00000000-0000-0000-C000-000000000046
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Get/>
</s:Body>
</s:Envelope>
The following shows the corresponding response message:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/pullport</wsa:To>
<wsa:Action>
http://www.w3.org/2011/03/ws-tra/GetResponse
</wsa:Action>
<wsa:MessageID>
urn:uuid:0000010e-0000-0000-C000-000000000046
</wsa:MessageID>
<wsa:RelatesTo>
urn:uuid:00000000-0000-0000-C000-000000000046
</wsa:RelatesTo>
</s:Header>
<s:Body>
<wst:GetResponse>
<wst:Representation>
<xxx:Customer>
<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>
<xxx:address>123 Main Street</xxx:address>
<xxx:city>Manhattan Beach</xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
</wst:Representation>
</wst:GetResponse>
</s:Body>
</s:Envelope>
In this example, the representation of the resource is the following XML
element:
<xxx:Customer>
<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>
<xxx:address>123 Main Street</xxx:address>
<xxx:city>Manhattan Beach</xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
4.2 Put
This specification defines one Web service operation (Put) for
updating a resource.
This operation MAY be supported by compliant WS-Transfer resources.
A resource MAY accept updates that provide different XML
representations than that returned by the resource; in such a
case, the semantics of the update operation is defined by
the resource.
Unless otherwise specified by an extension, this operation will
replace the entire XML representation of the
resource with the resource representation in the Put request message,
or if the Put request message contains instructions, update the XML
representation based on those instructions. When this operation is
used to replace the entire XML representation, any OPTIONAL values
(elements or attributes) not
specified in the Put request message MUST be set to a
resource-specific default value.
The Put request message MUST be of the following form:
[Action]
http://www.w3.org/2011/03/ws-tra/Put
[Body]
<wst:Put Dialect="xs:anyURI"? ...>
<wst:Representation ...>
xs:any?
<wst:Representation>?
xs:any*
</wst:Put>
The following describes additional, normative constraints on the
outline listed above:
- [Body]/wst:Put@Dialect
When this OPTIONAL attribute is present it contains a IRI that
refers to additional information for the service on how to
process this element. If the attribute is present but the
dialect IRI is not known then the service MUST generate an
wst:UnknownDialect fault. There is no default value for the
attribute. If the attribute is absent, then the base
behavior is used.
- [Body]/wst:Put@Dialect="http://www.w3.org/2011/03/ws-fra"
The WS-Fragment [WS-Fragment] specification defines
this dialect IRI. Use of this IRI indicates that the contents
of the Put element MUST be processed as specified by the
WS-Fragment [WS-Fragment] specification.
- [Body]/wst:Put/wst:Representation
This OPTIONAL element acts as a container for the
full representation
of the resource. This element MUST be present if the Dialect
attribute is absent. This element MAY have no children. This
case MUST be interpreted as a request to remove the
resource's representation, not the resource itself.
If the request message reaches a conformant implementation of
WS-Transfer and the message refers to an unknown resource, then the
implementation MUST generate a wst:UnknownResource fault.
A Put request MUST be targeted at the resource whose representation is
desired to be updated, as described in
3 Terminology and Notation of this specification.
The replacement representation could be considered to be invalid if
it does not conform to the schema(s) for the target resource, is
empty and the implementation does not support empty representations, or
otherwise violates some cardinality or type constraint.
If an implementation that validates the presented representation
detects that the presented representation is
invalid for the target resource, then the implementation MUST generate
a wst:InvalidRepresentation fault.
The replacement representation could contain within it element or
attribute values that are different than their corresponding values in
the current representation. Such changes could affect elements or
attributes that, for whatever reason, the implementation does not wish
to allow the client to change. An implementation MAY choose to ignore
such elements or attributes. If an implementation does not ignore
those elements or attributes, it MUST generate a wst:PutDenied fault.
See 6 Faults.
Other components of the outline above are not
further constrained by this specification.
A successful Put operation updates the current representation
associated with the targeted resource. An unsuccessful Put operation
does not affect the resource.
If the resource accepts a Put request and performs the requested
update, it MUST reply with a response of the following form:
[Action]
http://www.w3.org/2011/03/ws-tra/PutResponse
[Body]
<wst:PutResponse ...>
<wst:Representation ...>
xs:any?
</wst:Representation>?
xs:any*
</wst:PutResponse>- [Body]/wst:PutResponse/wst:Representation
This OPTIONAL element acts as a container for the full
representation of the resource. This element is intended for
use as an optimization to save the client the overhead of
having to perform a subsequent Get operation. A service
MAY include this element to return the current
representation of the resource. This element MAY have no
children in cases where there is no resource representation.
Other components of the outline above are not further constrained by this
specification.
The following shows a sample SOAP envelope containing a Put request:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam123.example.org/sender
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.org/pushport</wsa:To>
<xxx:CustomerID wsa:IsReferenceParameter="true">
732199
</xxx:CustomerID>
<xxx:Region wsa:IsReferenceParameter="true">
EMEA
</xxx:Region>
<wsa:Action>
http://www.w3.org/2011/03/ws-tra/Put
</wsa:Action>
<wsa:MessageID>
urn:uuid:00000000-0000-0000-C000-000000000047
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Put>
<wst:Representation>
<xxx:Customer>
<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>
<xxx:address>321 Main Street</xxx:address>
<xxx:city>Manhattan Beach</xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
</wst:Representation>
</wst:Put>
</s:Body>
</s:Envelope>
The following shows the corresponding response message indicating
success:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/sender</wsa:To>
<wsa:Action>
http://www.w3.org/2011/03/ws-tra/PutResponse
</wsa:Action>
<wsa:MessageID>
urn:uuid:0000010e-0000-0000-C000-000000000047
</wsa:MessageID>
<wsa:RelatesTo>
urn:uuid:00000000-0000-0000-C000-000000000047
</wsa:RelatesTo>
</s:Header>
<s:Body>
<wst:PutResponse/>
</s:Body>
</s:Envelope>
4.3 Delete
This specification defines one Web service operation (Delete) for
deleting a resource in its entirety.
This operation MAY be supported by compliant WS-Transfer resources.
The Delete request message MUST be of the following form:
[Action]
http://www.w3.org/2011/03/ws-tra/Delete
[Body]
<wst:Delete Dialect="xs:anyURI"? ...>
xs:any*
</wst:Delete>
The following describes additional, normative constraints on the
outline listed above:
- [Body]/wst:Delete
This is a REQUIRED element that has no defined child element
content.
- [Body]/wst:Delete@Dialect
When this OPTIONAL attribute is present it contains a IRI that
refers to additional information for the service on how to
process this element. If the attribute is present but the
dialect IRI is not known then the service MUST generate an
wst:UnknownDialect fault. There is no default value for the
attribute. If the attribute is absent, then the base
behavior is used.
If the request message reaches a conformant implementation of
WS-Transfer and the message refers to an unknown resource, then the
implementation MUST generate a wst:UnknownResource fault.
A Delete request MUST be targeted at the resource to be deleted as
described in 3 Terminology and Notation of this
specification.
Other components of the outline above are not further constrained by
this specification.
A successful Delete operation deletes the targeted resource.
If the resource accepts a Delete request, it MUST reply with a
response of the following form:
[Action]
http://www.w3.org/2011/03/ws-tra/DeleteResponse
[Body]
<wst:DeleteResponse ...>
xs:any*
</wst:DeleteResponse>- [Body]/wst:DeleteResponse
This REQUIRED element has no defined child element content.
Other components of the outline above are not further constrained
by this specification.
The following shows a sample SOAP envelope containing a Delete
request:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam123.example.org/sender
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.org/pushport</wsa:To>
<xxx:CustomerID wsa:IsReferenceParameter="true">
732199
</xxx:CustomerID>
<xxx:Region wsa:IsReferenceParameter="true">
EMEA
</xxx:Region>
<wsa:Action>
http://www.w3.org/2011/03/ws-tra/Delete
</wsa:Action>
<wsa:MessageID>
urn:uuid:00000000-0000-0000-C000-000000000049
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Delete/>
</s:Body>
</s:Envelope>
The following shows the corresponding response message indicating
success:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/sender</wsa:To>
<wsa:Action>
http://www.w3.org/2011/03/ws-tra/DeleteResponse
</wsa:Action>
<wsa:MessageID>
urn:uuid:0000010e-0000-0000-C000-000000000049
</wsa:MessageID>
<wsa:RelatesTo>
urn:uuid:00000000-0000-0000-C000-000000000049
</wsa:RelatesTo>
</s:Header>
<s:Body>
<wst:DeleteResponse/>
</s:Body>
</s:Envelope>
5 Resource Factory Operations
5.1 Create
This specification defines one Web service operation (Create) for
creating a resource and providing its initial representation.
This operation MAY be supported by compliant WS-Transfer resource
factories.
In some cases, the initial representation MAY constitute the
representation of a logical constructor for the resource and can
thus differ structurally from the representation returned by Get or
the one used by Put. This is because
the parameterization requirement for creating a resource is
often distinct from the steady-state representation of the resource.
Implementations SHOULD provide metadata which describes the use of
the representation and how it relates to the resource which is
created, but such mechanisms are beyond the scope of this
specification. The resource factory that receives a
Create request will allocate a new resource that is initialized
from the presented representation. The new resource will be assigned
a service-determined endpoint reference that is returned in the
response message.
The Create request message MUST be of the following form:
[Action]
http://www.w3.org/2011/03/ws-tra/Create
[Body]
<wst:Create Dialect="xs:anyURI"? ...>
<wst:Representation ...>
xs:any?
</wst:Representation>?
xs:any*
</wst:Create>
The following describes additional, normative constraints on the
outline listed above:
- [Body]/wst:Create@Dialect
When this OPTIONAL attribute is present it contains a IRI that
refers to additional information for the service on how to
process this element. If the attribute is present but the
dialect IRI is not known then the service MUST generate an
wst:UnknownDialect fault. There is no default value for the
attribute. If the attribute is absent, then the base
behavior is used.
- [Body]/wst:Create/wst:Representation
This OPTIONAL element acts as a container for the full
representation of the resource. If this element is not
present the resource MUST be created using default values
(equivalent to a null constructor). This element MAY have
no children. This case MUST be interpreted as a request to create
a new resource with
an empty representation (equivalent to an empty constructor).
A Create request MUST be targeted at a resource factory capable of
creating the desired new resource. This factory is distinct from the
resource being created (which by definition does not exist prior to
the successful processing of the Create request message).
The representation could be considered to be invalid if it does
not conform to the schema(s) for the target resource, is empty and
the implementation does not support empty representations, or
otherwise violates some cardinality or type constraint. If an
implementation that validates the presented representation detects
that the presented representation is invalid for the target
resource, then the implementation MUST generate a
wst:InvalidRepresentation fault.
Other components of the outline above are not further constrained by
this specification.
If the resource factory accepts a Create request, it MUST reply with
a response of the following form:
[Action]
http://www.w3.org/2011/03/ws-tra/CreateResponse
[Body]
<wst:CreateResponse ...>
<wst:ResourceCreated>endpoint-reference</wst:ResourceCreated>
<wst:Representation ...>
xs:any?
</wst:Representation>?
xs:any*
</wst:CreateResponse>- [Body]/wst:CreateResponse/wst:ResourceCreated
This REQUIRED element MUST be an endpoint reference for the
newly created resource. This endpoint reference MUST
identify the resource for future Get, Put, and Delete
operations.
- [Body]/wst:CreateResponse/wst:Representation
This OPTIONAL element acts as a container for the full
representation of the resource. This element is intended for
use as an optimization to save the client the overhead of
having to perform a subsequent Get operation. A service
MAY include this element to return the current representation
of the resource. This element MAY have no children in cases
where there is no resource representation.
Other components of the outline above are not further constrained by
this specification.
The following shows a sample SOAP envelope containing a Create
request:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam123.example.org/sender
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.org/pushport/CustomerSpace</wsa:To>
<wsa:Action>
http://www.w3.org/2011/03/ws-tra/Create
</wsa:Action>
<wsa:MessageID>
urn:uuid:00000000-0000-0000-C000-000000000048
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Create>
<wst:Representation>
<xxx:Customer>
<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>
<xxx:address>123 Main Street</xxx:address>
<xxx:city>Manhattan Beach</xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
</wst:Representation>
</wst:Create>
</s:Body>
</s:Envelope>
The following shows the corresponding response message indicating
success:
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wst="http://www.w3.org/2011/03/ws-tra"
xmlns:xxx="http://fabrikam123.example.com/resource-model" >
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/sender</wsa:To>
<wsa:Action>
http://www.w3.org/2011/03/ws-tra/CreateResponse
</wsa:Action>
<wsa:MessageID>
urn:uuid:0000010e-0000-0000-C000-000000000048
</wsa:MessageID>
<wsa:RelatesTo>
urn:uuid:00000000-0000-0000-C000-000000000048
</wsa:RelatesTo>
</s:Header>
<s:Body>
<wst:CreateResponse>
<wst:ResourceCreated>
<wsa:Address>http://www.example.org/pushport</wsa:Address>
<wsa:ReferenceParameters>
<xxx:CustomerID>732199</xxx:CustomerID>
<xxx:Region>EMEA</xxx:Region>
</wsa:ReferenceParameters>
</wst:ResourceCreated>
</wst:CreateResponse>
</s:Body>
</s:Envelope>
6 Faults
All fault messages defined in this specification MUST be sent
according to the rules and usage described in
[WS-Addressing 1.0 SOAP Binding]
Section 6 for encoding SOAP 1.1 and SOAP 1.2 faults.
The [Action] property below MUST be used for faults
defined in this specification:
The definitions of faults in this section use the following properties:
[Code] The fault code.
[Subcode] The fault subcode.
[Reason] The English language reason element.
[Detail] The detail element. If absent, no detail element
is defined for the fault.
The properties above bind to a SOAP 1.2 fault as follows:
<s12:Envelope>
<s12:Header>
<wsa:Action> [Action] </wsa:Action>
<!-- Headers elided for brevity. -->
</s12:Header>
<s12:Body>
<s12:Fault>
<s12:Code>
<s12:Value>[Code]</s12:Value>
<s12:Subcode>
<s12:Value>[Subcode]</s12:Value>
</s12:Subcode>
</s12:Code>
<s12:Reason>
<s12:Text xml:lang="en">[Reason]</s12:Text>
</s12:Reason>
<s12:Detail>
[Detail]
...
</s12:Detail>
</s12:Fault>
</s12:Body>
</s12:Envelope>The properties bind to a SOAP 1.1 fault as follows:
<s11:Envelope>
<s12:Header>
<wsa:Action> [Action] </wsa:Action>
<!-- Headers elided for brevity. -->
</s12:Header>
<s11:Body>
<s11:Fault>
<faultcode>[Subcode]</faultcode>
<faultstring xml:lang="en">[Reason]</faultstring>
<detail>
[Detail]
...
</detail>
</s11:Fault>
</s11:Body>
</s11:Envelope>
6.1 InvalidRepresentation
This fault MUST be generated when an incorrect representation is
sent in a wst:Put or wst:Create message.
| [Code] | s:Sender |
|---|
| [Subcode] | wst:InvalidRepresentation |
|---|
| [Reason] | The supplied representation is invalid |
|---|
| [Detail] | none |
|---|
6.2 UnknownDialect
This fault MUST be generated when a service detects an unknown
Dialect IRI in a request message.
| [Code] | s:Sender |
|---|
| [Subcode] | wst:UnknownDialect |
|---|
| [Reason] |
The specified Dialect IRI is not known.
|
|---|
| [Detail] | The unknown IRI if specified |
|---|
6.3 PutDenied
This fault MUST be generated when a Put request message attempts
to modify a portion of a resource but is not allowed to do so.
| [Code] | s:Sender |
|---|
| [Subcode] | wst:UpdateDenied |
|---|
| [Reason] |
One or more elements or attributes cannot be updated.
|
|---|
| [Detail] |
An OPTIONAL list of the QNames of the elements or
attributes that are not allowed to be updated. |
|---|
6.4 UnknownResource
This fault MUST be generated when a request specifies a resource
that is not known.
| [Code] | s:Sender |
|---|
| [Subcode] | wst:UnknownResource |
|---|
| [Reason] |
The resource is not known.
|
|---|
| [Detail] | none |
|---|
7 Security Considerations
This specification considers two sets of security requirements, those
of the applications that use the WS-Transfer protocol and those of
the protocol itself.
This specification makes no assumptions about the security requirements
of the applications that use WS-Transfer. However, once those
requirements have been satisfied within a given operational context,
the addition of WS-Transfer to this operational context can not
undermine the fulfillment of those requirements; the use of
WS-Transfer SHOULD NOT create additional attack vectors within
an otherwise secure system.
The material below is not a "check list". There are many other
security concerns that need to be considered when implementing or
using this protocol. Implementers and users of this protocol are urged
to perform a security analysis to determine their particular threat
profile and the appropriate responses to those threats.
7.1 Protecting Resources
Both resources and the information that makes up their representation
might be sensitive. In these cases, it is advisable for resource
managers to authenticate and authorize clients attempting Get, Put,
or Delete operations. To protect representations sent over a network,
the wst:Get, wst:GetResponse, wst:Put, and wst:PutResponse messages
ought to have the appropriate authenticity, integrity, and
confidentiality measures applied.
7.2 Protecting Resource Factories
In cases where resources and/or the information that makes up their
representation are sensitive so, too, are the services that create
these resources. In such cases it is advisable for resource factories
to authenticate and authorize clients attempting Create operations.
To protect representations sent over a network, wst:CreateResponse
messages that include representations ought to have the appropriate
authenticity, integrity, and confidentiality measures applied.
8 WS-Transfer Metadata
An endpoint MAY indicate its support of WS-Transfer, or its features,
by including the WS-Transfer TransferResource or TransferResourceFactory
Policy assertions within its WSDL. By
doing so the endpoint is indicating that the corresponding WS-Transfer
operations are supported by that endpoint even though they are implicit
and do not explicitly appear in its WSDL
(i.e. the WS-Transfer operations do not appear in the WSDL that MAY be
retrievable by using a WS-MetadataExchange GetWSDL to that endpoint).
The WS-Transfer WSDL containing the operations indicated by the
TransferResource or TransferResourceFactory assertions MAY be exposed
by including the WSDL as a child of the appropriate Policy assertion or
by including a reference to it using the mex:Location or mex:Reference
element (as described in
WS-MetadataExchange [WS-MetadataExchange] Section 9).
This WS-Transfer WSDL can be annotated to indicate any endpoint
specific metadata that might be needed by clients interacting with
the WS-Transfer operations.
For example, the WSDL might have policy assertions
that indicate a particular security mechanism used to protect
the WS-Transfer operations supported by this endpoint.
8.1 TransferResource Assertion
Services indicate support for the
WS-Transfer's definition of a Transfer Resource
through the use of the Web Services
Policy - Framework [WS-Policy] and Web Services Policy -
Attachment [WS-Policy Attachment] specifications.
This specification defines a policy assertion (wst:TransferResource).
The normative outline of this assertion is:
<wst:TransferResource ...>
<wst:PutOperationSupported .../> ?
<wst:DeleteOperationSupported .../> ?
<wst:FaultOnPutDenied .../> ?
<wst:Dialect URI='xs:anyURI ...>
xs:any*
</wst:Dialect> *
<wst:Resource ...> xs:QName </wst:Resource> ?
xs:any*
</wst:TransferResource>
The following describes additional, normative constraints on the
outline listed above:
- /wst:TransferResource
This policy assertion has Endpoint Policy Subject. When present in a
policy alternative, it indicates that the subject is a Transfer
resource
and the WS-Transfer protocol MUST
be used when communicating with this endpoint.
Unless
support for OPTIONAL operations is explicitly indicated by either
the PutOperationSupported or DeleteOperationSupported parameters only
the Get operation is supported.
- /wst:TransferResource/wst:PutOperationSupported
When present, this OPTIONAL parameter indicates that the Put
operation is supported by this endpoint.
- /wst:TransferResource/wst:DeleteOperationSupported
When present, this OPTIONAL parameter indicates that the Delete
operation is supported by this endpoint.
- /wst:TransferResource/wst:FaultOnPutDenied
When present, this OPTIONAL parameter indicates that attempts to
change portions of the representation that are read-only will
generate a wst:PutDenied fault. If this parameter is not present,
attempts to modify read-only portions of the resource representation
will be ignored without any fault being generated.
- /wst:TransferResource/wst:Dialect
When present, this OPTIONAL parameter indicates support for the
specified Dialect IRI.
- /wst:TransferResource/wst:Dialect/xs:any
This extensibility point allows for additional Dialect specific
metadata to be included within the policy assertion. Any metadata
that appears is scoped to the use of the specified Dialect URI.
- /wst:TransferResource/wst:Resource
When present, this OPTIONAL parameter provides the QName referencing
the Global Element Declaration (GED) or type of this resource. This
QName can be used in order to retrieve the schema of the resource.
If an endpoint uses this parameter then it MUST only accept and
transmit XML representations of the resource that adhere to the
scheme referenced by this QName.
- /wst:TransferResource/xs:any
This extensibility point allows for additional WS-Transfer
specific metadata to be included within the policy assertion -
e.g. WS-Transfer WSDL, or nested policy assertions related to the
WS-Transfer message exchanges. Any metadata that appears is scoped
to the operations and features of the WS-Transfer specification.
8.2 TransferResourceFactory Assertion
Services indicate support for
WS-Transfer's definition of a Transfer Resource Factory
through the use of the Web Services
Policy - Framework [WS-Policy] and Web Services Policy -
Attachment [WS-Policy Attachment] specifications.
This specification defines a policy assertion
(wst:TransferResourceFactory).
The normative outline of this assertion is:
<wst:TransferResourceFactory ...>
<wst:Resource ...> xs:QName </wst:Resource> *
<wst:Dialect URI="xs:anyURI" ...>
xs:any*
</wst:Dialect> *
xs:any*
</wst:TransferResourceFactory>
The following describes additional, normative constraints on the
outline listed above:
- /wst:TransferResourceFactory
This policy assertion has Endpoint Policy Subject. When present in a
policy alternative, it indicates that the subject is a resource
factory
and the WS-Transfer protocol MUST
be used when communicating with this endpoint.
- /wst:TransferResourceFactory/wst:Resource
When present, this repeating OPTIONAL parameter indicates the QName
referencing the GED of one type of resource representation
supported by this factory.
If an endpoint uses this parameter then it MUST only accept and
transmit XML representations of the resource that adhere to the
scheme referenced by one of these QNames.
- /wst:TransferResourceFactory/wst:Dialect
When present, this OPTIONAL parameter indicates support for the
specified Dialect IRI.
- /wst:TransferResourceFactory/wst:Dialect/xs:any
This extensibility point allows for additional Dialect specific
metadata to be included within the policy assertion. Any metadata
that appears is scoped to the use of the specified Dialect URI.
- /wst:TransferResourceFactory/xs:any
This extensibility point allows for additional WS-Transfer
specific metadata to be included within the policy assertion -
e.g. WS-Transfer WSDL, or nested policy assertions related to the
WS-Transfer message exchanges. Any metadata that appears is scoped
to the operations and features of the WS-Transfer specification.
9 Acknowledgements
This specification has been developed as a result of joint
work with many individuals and teams, including:
Alessio Soldano (Red Hat),
Ashok Malhotra (Oracle Corp.),
Asir Vedamuthu (Microsoft Corp.),
Bob Freund (Hitachi, Ltd.),
Bob Natale (MITRE Corp.),
David Snelling (Fujitsu, Ltd.),
Doug Davis (IBM),
Fred Maciel (Hitachi, Ltd.),
Geoff Bullen (Microsoft Corp.),
Gilbert Pilz (Oracle Corp.),
Greg Carpenter (Microsoft Corp.),
Jeff Mischkinsky (Oracle Corp.),
Katy Warr (IBM),
Li Li (Avaya Communications),
Mark Little (Red Hat),
Martin Chapman (Oracle Corp.),
Paul Fremantle (WSO2),
Paul Nolan (IBM),
Prasad Yendluri (Software AG),
Ram Jeyaraman (Microsoft Corp.),
Sreedhara Narayanaswamy (CA),
Sumeet Vij (Software AG),
Tom Rutt (Fujitsu, Ltd.),
Vikas Varma (Software AG),
Wu Chou (Avaya Communications),
Yves Lafon (W3C/ERCIM).
10 References
10.1 Normative References
- BP12
-
WS-I Profile, Basic Profile Version 1.2
, R. Chumbley, et al, Editors.
Web Services Interoperability Organization (WS-I), 9 November 2010.
Available at http://ws-i.org/profiles/BasicProfile-1.2-2010-11-09.html.
- BP20
-
WS-I Profile, Basic Profile Version 2.0
, R. Chumbley, et al, Editors.
Web Services Interoperability Organization (WS-I), 9 November 2010.
Available at http://ws-i.org/profiles/BasicProfile-2.0-2010-11-09.html.
- RFC 2119
-
Key words for use in RFCs to Indicate Requirement Levels
, S. Bradner, Author.
Internet Engineering Task Force, March 1997.
Available at http://www.ietf.org/rfc/rfc2119.txt.
- RFC 3987
-
Internationalized Resource Identifiers (IRIs)
, M. Duerst and M. Suignard, Authors.
Internet Engineering Task Force, January 2005.
Available at http://www.ietf.org/rfc/rfc3987.txt.
- SOAP11
-
W3C Note, "Simple Object Access Protocol (SOAP) 1.1"
, D. Box, et al, Editors.
World Wide Web Consortium (W3C), 8 May 2000.
Available at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
- SOAP12
-
W3C Recommendation, "SOAP Version 1.2 Part 1: Messaging Framework"
, M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielson,
Editors.
World Wide Web Consortium (W3C), 27 April 2007.
Available at http://www.w3.org/TR/soap12-part1/.
- WS-Addressing
-
W3C Recommendation, "Web Services Addressing 1.0 (WS-Addressing)"
, M. Gudgin, M. Hadley, T. Rogers, Editors.
World Wide Web Consortium (W3C), 9 May 2006.
Available at http://www.w3.org/TR/ws-addr-core.
- WS-Addressing 1.0 SOAP Binding
-
W3C Recommendation, "Web Services Addressing 1.0 - SOAP Binding"
, M. Gudgin, M. Hadley, T. Rogers, Editors.
World Wide Web Consortium (W3C), 9 May 2006.
Available at http://www.w3.org/TR/ws-addr-soap.
- WS-Policy
-
W3C Recommendation, "Web Services Policy (WS-Policy) 1.5 - Framework"
, A. Vedamuthu, et al., Editors.
World Wide Web Consortium (W3C), 4 September 2007.
Available at http://www.w3.org/TR/ws-policy/.
- WS-Policy Attachment
-
W3C Recommendation, "Web Services Policy (WS-Policy) 1.5 - Attachment"
, A. Vedamuthu, et al., Editors.
World Wide Web Consortium (W3C), 4 September 2007.
Available at http://www.w3.org/TR/ws-policy-attach.
- WSDL11
-
W3C Note, "Web Services Description Language (WSDL) 1.1"
, E. Christensen, et al., Editors.
World Wide Web Consortium (W3C), 15 March 2001
Available at http://www.w3.org/TR/2001/NOTE-wsdl-20010315.
- XML Infoset
-
W3C Recommendation, "XML Information Set (Second Edition)"
, J. Cowan, R. Tobin, Editors.
World Wide Web Consortium (W3C), 4 February 2004.
Available at http://www.w3.org/TR/xml-infoset.
- XMLSchema - Part 1
-
W3C Recommendation, "XML Schema Part 1: Structures (Second Edition)"
, H. Thompson, et al., Editors.
World Wide Web Consortium (W3C), 28 October 2004.
Available at http://www.w3.org/TR/xmlschema-1/.
- XMLSchema - Part 2
-
W3C Recommendation, "XML Schema Part 2: Datatypes (Second Edition)"
, P. Biron, A. Malhotra, Editors.
World Wide Web Consortium (W3C), 28 October 2004.
Available at http://www.w3.org/TR/xmlschema-2/.
10.2 Informative References
- WS-Fragment
-
W3C Working Group Draft, "Web Services Fragment (WS-Fragment) 1.0"
, D. Davis, et al., Editors.
World Wide Web Consortium (W3C), 15 September 2009.
Available at http://www.w3.org/TR/ws-fragment.
- WS-MetadataExchange
-
W3C Working Group Draft, "Web Services Metadata Exchange
(WS-MetadataExchange) 1.1"
, D. Davis, et al., Editors.
World Wide Web Consortium (W3C), 15 September 2009.
Available at http://www.w3.org/TR/ws-metadata-exchange.