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/.
The This is
the 15 November 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 Membership and other interested parties are
invited Web Services Activity
.
The public is encouraged to
review the document and send comments
to the Working Group's public mailing list public-ws-resource-access-comments@w3.org
mailing list (
public archive ) until 4 November 2011
. ). See W3C mailing list and archive usage
guidelines . Advisory Committee
Representatives should consult their WBS questionnaires .
No substantive changes were made as a result of the Candidate Proposed
Recommendation phase (see also diff
, test
scenario and implementation
report ).
A Proposed Recommendation is a
specification that is under review by the W3C Advisory Committee
for endorsement as a W3C Recommendation . It is is a mature
This document that has been widely
reviewed by W3C Members, by software
developers, and has been shown to be
implementable. by other W3C
encourages everybody to implement this
specification. Publication as a Proposed Recommendation does not
imply endorsement groups and interested
parties, and is endorsed by the Director as a W3C Membership. This Recommendation. It is a draft stable document
and may be updated, replaced or obsoleted by
other documents at any time. It is inappropriate to cite this
document used as other than work reference
material or cited from another document. W3C's role in
progress. It has been produced by
making the Web
Services Resource Access Working Group (WG), which
Recommendation is part to draw attention to
the specification and to promote its widespread deployment. This
enhances the functionality and interoperability of the
W3C Web Services Activity . 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:Address>
<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:Address>
<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:Address>
<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:Address>
<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
.