All
messages defined by this specification MUST be sent to a Web service that is
addressable by an EPR [WS-Addressing].
This specification defines one Web service operation
(Get) for fetching a one-time snapshot of the representation of a resource.
The Get request message MUST be of the
following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Get
</wsa:Action>
<wsa:MessageID>xs:anyURI</wsa:MessageID>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:Get ...>
xs:any *
</wst:Get>
</s:Body>
</s:Envelope>
The following describes additional, normative
constraints on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This
required element MUST contain the value http://www.w3.org/2009/02/ws-tra/Get. If a SOAP Action URI is also present in the
underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/wst:Get
Unless an
extension specification is in use, tThis REQUIRED
element MUST
not contain any MAY contain child elements that can be
used for extensibility purposes. .
A Get request MUST be targeted at the resource
whose representation is desired as described in 2 Terminology and Notation of this
specification.
As per the SOAP processing model, other specifications
may introduce various types of extensions to the semantics of this message
which are enabled through headers tagged with s:mustUnderstand="true". Such extensions may define how resource or subsets of it are to be
retrieved or transformed prior to retrieval. Specifications which define such
extensions MUST allow processing the basic Get request message without those
extensions. Since the response may not be sent to the original sender,
extension specifications should consider adding a corresponding SOAP header
value in the response to signal to the receiver that the extension is being
used.
Implementations may respond with a fault message using
the standard fault codes defined in WS-Addressing (e.g., wsa:ActionNotSupported).
Other components of the outline above are not further constrained by this
specification.
If the resource accepts a Get request, it MUST reply with
a response of the following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/GetResponse
</wsa:Action>
<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:GetResponse
...>
xs:any *+
</wst:GetResponse>
</s:Body>
</s:Envelope>
The following describes additional, normative constraints
on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the value
http://www.w3.org/2009/02/ws-tra/GetResponse. If a SOAP Action URI is also
present in the underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/wst:GetResponse
Unless an extension specification is in use, tThis
REQUIRED element MUST contain exactly at least one child
element -
the representation of the resource. The presence of subsequent child elements
is service-specific and MAY be controlled by the presence or extension-specific
SOAP headers in the original request. .
Other components of the outline above are not further
constrained by this specification.
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>732199</xxx:CustomerID>
<xxx:Region>EMEA</xxx:Region>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Get
</wsa:Action>
<wsa:MessageID>
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:Action>
http://www.w3.org/2009/02/ws-tra/GetResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000046
</wsa:MessageID>
<wsa:RelatesTo>
uuid:00000000-0000-0000-C000-000000000046
</wsa:RelatesTo>
</s:Header>
<s:Body>
<GetResponse>
<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>
</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>
This specification defines one Web service
operation (Put) for updating a resource by providing a replacement
representation. 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.
The Put request message MUST be of the
following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Put
</wsa:Action>
<wsa:MessageID>xs:anyURI</wsa:MessageID>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body...>
<wst:Put ...>
xs:any *+
>/wst:Put>
</s:Body>
</s:Envelope>
The following describes additional, normative
constraints on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This
required element MUST contain the value http://www.w3.org/2009/02/ws-tra/Put.
If a SOAP Action URI is also present in the underlying transport, its value
MUST convey the same value.
/s:Envelope/s:Body/Put
Unless and extension specification is in use, tThis
REQUIRED element MUST contain exactly at least one child
element.
- the representation to be used for the update. All other children SHOULD be
ignored by the service.
A Put request MUST be targeted at the resource
whose representation is desired to be replaced, as described in 2 Terminology and Notation
of this specification. As per the SOAP processing model, other specifications
MAY introduce various types of extensions to this message which are enabled
through headers tagged with s:mustUnderstand="true". Such extensions may require that a full or partial update should be
accomplished using symbolic, instruction-based, or other methodologies.
Extension specifications MAY also define extensions to
the original Put request, enabled by OPTIONAL SOAP headers, which control the
nature of the response, as discussed in remarks on the PutResponse
below.
Specifications which define any of these extensions MUST
allow processing the Put message without such extensions.
In addition to the standard fault codes defined in
WS-Addressing, implementations MAY use the fault code wst:InvalidRepresentation
if the presented representation is invalid for the target resource. See 5 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.
If the resource accepts a Put request and performs the
requested update, it MUST reply with a response of the following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/PutResponse
</wsa:Action>
<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:PutResponse
...>
xs:any *?
</wst:PutResponse>
</s:Body>
</s:Envelope>
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the value
http://www.w3.org/2009/02/ws-tra/PutResponse. If a SOAP Action URI is also
present in the underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/PutResponse
Unless an extension specification is in use, tThis
REQUIRED element MUST contain no more than at least one child
element (the current representation of the resource) if the updated
representation differs from the representation sent in the Put request message. The presence
of additional child elements which contain other information pertaining to the
update is service-specific.
As an optimization and as a service to the
requester, this element SHOULD be empty if the updated representation does not
differ from the representation sent in the Put request message; that is, if the
service accepted the new representation verbatim.
Such a response (an empty wst:PutResponse)
implies that the update request was successful in its entirety (assuming no
intervening mutating operations are performed). A service MAY return the
current representation of the resource as the initial child of the
wst:PutResponse element even in this case, however.
Extension specifications MAY define
extensions to the original Put request, enabled by OPTIONAL header values, which
specifically control the presence, absence, or format of the updated
representation or other child elements in the PutResponse
in order to optimize the response. In the absence of such headers, the behavior
MUST be as described above. Specifications which define any of these extensions
MUST allow processing the Put message without such extensions. Since the
response may not be sent to the original sender, extension specifications
should consider adding a corresponding SOAP header value in the response to
signal to the receiver that the extension is being used.
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>732199</xxx:CustomerID>
<xxx:Region>EMEA</xxx:Region>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Put
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000047
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Put>
<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: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:Action>
http://www.w3.org/2009/02/ws-tra/PutResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000047
</wsa:MessageID>
<wsa:RelatesTo>
uuid:00000000-0000-0000-C000-000000000047
</wsa:RelatesTo>
</s:Header>
<s:Body>
<wst:PutResponse/>
</s:Body/>
</s:Envelope>
This specification defines one Web service
operation (Delete) for deleting a resource in its entirety.
Extension specifications MAY define
extensions to the Delete request, enabled by OPTIONAL header values, which
specifically control preconditions for the Delete to succeed and which may
control the nature or format of the response. Since the response may not be
sent to the original sender, extension specifications should consider adding a
corresponding SOAP header value in the response to signal to the receiver that
the extension is being used.
The Delete request message MUST be of the
following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Delete
</wsa:Action>
<wsa:MessageID>xs:anyURI</wsa:MessageID>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:Delete ...>
xs:any *
</wst:Delete>
</s:Body>
</s:Envelope>
The following describes additional, normative
constraints on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This
required element MUST contain the value http://www.w3.org/2009/02/ws-tra/Delete. If a SOAP Action URI is also present in the
underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/wst:Delete
Unless an
extension specification is in use, tThis REQUIRED
element MUST
NOT MAY contain any child elements that can be
used for extensibility purposes.
A Delete request MUST be targeted at the
resource to be deleted as described in 2 Terminology and Notation of this
specification.
Implementations may respond with a fault message using
the standard fault codes defined in WS-Addressing (e.g., wsa:ActionNotSupported).
Other components of the outline above are not further constrained by this
specification.
A successful Delete operation invalidates the current
representation associated with the targeted resource.
If the resource accepts a Delete request, it MUST reply
with a response of the following form:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/DeleteResponse
</wsa:Action>
<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:DeleteResponse
...>
xs:any *?
</wst:DeleteResponse>
</s:Body>
</s:Envelope>
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/DeleteResponse. If a SOAP Action URI is also present in the underlying transport, its
value MUST convey the same value.
/s:Envelope/s:Body/wst:DeleteResponse
Unless an extension specification is in use, tThis
REQUIRED element MUST NOT MAY contain any a child
elements that can be
used for extensibility purposes.
Specifications which define extensions for use in the
original Delete request which control the format of the response MUST allow
processing the Delete message without such extensions.
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>732199</xxx:CustomerID>
<xxx:Region>EMEA</xxx:Region>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Delete
</wsa:Action>
<wsa:MessageID>
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:Action>
http://www.w3.org/2009/02/ws-tra/DeleteResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000049
</wsa:MessageID>
<wsa:RelatesTo>
uuid:00000000-0000-0000-C000-000000000049
</wsa:RelatesTo>
</s:Header>
<s:Body>
</wst:DeleteResponse>
</s:Body>
</s:Envelope>
This specification
defines one Web service operation (Create) for creating a resource and
providing its initial representation. In some cases, the initial representation
MAY constitute the representation of a logical constructor for the resource and
may thus differ structurally from the representation returned by Get or the one
required 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:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/Create
</wsa:Action>
<wsa:MessageID>xs:anyURI</wsa:MessageID>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:Create ...>
xs:any *
</wst:Create>
</s:Body>
</s:Envelope>
The following describes
additional, normative constraints on the outline listed above:
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/Create. If a SOAP Action URI is also present in the
underlying transport, its value MUST convey the same value.
/s:Envelope/s:Body/Create
Unless
an extension specification is in use, tIf this REQUIRED
element MUST
contains no more than one
children element then the first- child MUST be the literal
resource representation, a representation of the constructor for the resource,
or other instructions for creating the resource. All other
children SHOULD be ignored by the service. If this element
does not contain any children then the resource will be created using default
values.
Extensions
specifications MAY also define extensions to the original Create request,
enabled by OPTIONAL SOAP headers, which constrain the nature of the response,
as discussed in remarks on the CreateResponse below.Similarly, they may require headers which control the
interpretation of the wst:Create as part of the
resource creation process.
Such specifications MUST
also allow processing the Create message without such extensions.
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).
In addition to the
standard fault codes defined in WS-Addressing, implementations MAY use the
fault code wst:InvalidRepresentation if the presented
representation is invalid for the target resource. See 5 Faults.
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:
<s:Envelope ...>
<s:Header ...>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/CreateResponse
</wsa:Action>
<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>
<wsa:To>xs:anyURI</wsa:To>
...
</s:Header>
<s:Body ...>
<wst:CreateResponse
...>
<wst:ResourceCreated>endpoint-reference</wst:ResourceCreated>
xs:any *?
</wst:CreateResponse>
</s:Body>
</s:Envelope>
/s:Envelope/s:Header/wsa:Action
This required element MUST contain the value
http://www.w3.org/2009/02/ws-tra/CreateResponse. If a SOAP Action URI is also
present in the underlying transport, its value MUST convey the same value.
/s:Envelope/wst:CreateResponse
Unless an extension specification is in use, tThis
REQUIRED element MUST contain at least one child element, but no more than two
child elements. The first child element MUST be a , at a minimum,
a resource reference (wst:ResourceCreated
element) to the newly created resource.
By default, a service MUST also return the
current representation of the new resource as the second child of the wst:CreateResponse element if the created representation
logically differs from the representation sent in the Create request message.
That is, the initial representation is returned if one or more values present
in Create message was specifically overridden with a different value during
resource creation. If default values are used to complete a resource creation
which were not present in the Create message, then this does not constitute a
logical difference. The presence of additional child elements which
contain other information pertaining to the result of the Create operation is
service-specific.
As an optimization and as a service to the requestor,
the wst:CreateResponse element of the response
message SHOULD be empty, other than the ResourceCreated
element, if the created representation does not logically differ from the
representation sent in the Create request message; that is, if the service
accepted the new representation or creation instructions verbatim. Such a
response indicates that the request was completely successful (assuming no
intervening mutating operations are performed). A service MAY return the
current representation of the resource as the initial second child
of the wst:CreateResponse element even in this case,
however.
Extension specifications MAY define
extensions to the original Create request, enabled by OPTIONAL header values,
which specifically control the presence, absence, or format of the initial
representation or other child elements in the CreateResponse.
These headers MAY override the default behavior if they are marked with s:mustUnderstand="true". In the absence of such OPTIONAL headers, the behavior MUST be as
described in the previous paragraphs. Since the response may not be sent to the
original sender, extension specifications should consider adding a
corresponding SOAP header value in the response to signal to the receiver that
the extension is being used.
/s:Envelope/wst:CreateResponse/wst:ResourceCreated
This required element MUST contain a resource
reference for the newly created resource. This resource reference, represented
as an endpoint reference as defined in WS-Addressing, MUST identify the resource
for future Get, Put, and Delete operations.
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/2009/02/ws-tra/Create
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000048
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Create>
<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: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/2009/02/ws-tra"
xmlns:xxx="http://fabrikam123.example.com/resource-model"
>
<s:Header>
<wsa:To>http://www.fabrikam123.example.org/sender</wsa:Address>
<wsa:Action>
http://www.w3.org/2009/02/ws-tra/CreateResponse
</wsa:Action>
<wsa:MessageID>
uuid:0000010e-0000-0000-C000-000000000048
</wsa:MessageID>
<wsa:RelatesTo>
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>