Understanding Web Service
Resource Access
Geoff Bullen
Microsoft
Overview


Introduction to Resource Access Web Services
The Banking Scenario





Transfer
MetadataExchange
Enumeration
Eventing
References
Disclaimer

The example companies, organizations, products, domain
names, e-mail addresses, logos, people, places, and events
depicted herein are fictitious. No association with any
real company, organization, product, domain name, email
address, logo, person, places, or events is intended or
should be inferred.
Resource Access Specifications

WS-Transfer


WS-MetadataExchange


Enumerating a sequence of XML elements.
WS-Eventing


A general purpose metadata encapsulation format and a protocol for
retrieving Web service metadata.
WS-Enumeration


A general SOAP-based protocol for creating, retrieving, updating and
deleting XML representations of Web service-based resources.
Allows Web services to subscribe to or accept subscriptions for
event notification messages.
WS-ResourceTransfer

Extensions to WS-Transfer to define fragment-based operations.
Web Services Specifications
WS-Federation
WS-Management
Devices Profile
Metadata
WS-Discovery
Assurances
WS-Secure
Conversation
UDDI
WS-Atomic
Transaction
WS-Trust
WS-Security
WS-Reliable
Messaging
WS-Coordination
WS-Transfer
WS-Enumeration
WS-Eventing
SOAP
WS-Addressing
MTOM
WS-Metadata
Exchange
WS-Policy
Messaging
XML
Namespaces
MIME
WSDL
XML Schema
SOAP / UDP
XML Infoset
XML 1.0
Infrastructure
and Profiles
SOAP / HTTP
5
Foundation
SOAP Message – Request
<soap:Envelope>
<soap:Header>
<wsa:To>http://x.woodgrovebank.com/TransactionHistory</wsa:To>
<wsa:ReplyTo>
<wsa:Address>http://todd.adatum.com/customer</wsa:Address>
</wsa:ReplyTo>
<wsa:Action>http://x.woodgrovebank.com/GetHistory</wsa:Action>
<bank:AccID wsa:IsReferenceParameter=“true”>a1234567</bank:AccID>
…
</soap:Header>
<soap:Body />
</soap:Envelope>
SOAP Message - Response
<soap:Envelope>
<soap:Header>
<wsa:To>http://todd.adatum.com/customer</wsa:To>
<wsa:Action>http://x.woodgrovebank.com/HistoryResponse</wsa:Action>
<bank:AccID wsa:IsReferenceParameter=“true”>a1234567</bank:AccID>
…
</soap:Header>
<soap:Body>
<bank:Transactions>
<bank:Transaction id=”t14324”> info </bank:Transaction>
<bank:Transaction id=”t14325”> info </bank:Transaction>
<bank:Transaction id=”t14326”> info </bank:Transaction>
…
</bank:Transactions>
</soap:Body>
</soap:Envelope>
Let’s Go Banking

Todd Meadows wants to access his Woodgrove bank account.




Firstly Todd wants to see how much money he has in his bank account (WSTransfer).
When Todd sees his balance, he doesn’t think he has the right amount of money
available, and so wants to get his transaction history to find out what is going on.



Todd is a programmer at heart – “anything worth doing is worth doing with Web Services”
is his motto.
Woodgrove Bank provides Resource Access Web Services which Todd can use to
accomplish this task.
Unfortunately he does not exactly know how to execute this operation and must first
understand what is required in order to successfully see this information (WSMetadataExchange).
Todd now realizes that the number of records is far too long to be retrieved at
once, and so he wants to break this down into a number of more manageable
pieces of information (WS-Enumeration).
Finally Todd, after searching through his newly-chunked account transactions, has
found out that some strange person has been accessing his account without
permission, and so now he wants to be notified whenever any information in his
account changes (WS-Eventing).
Woodgrove Bank defines a bank account
A Transfer resource can be anything that is addressable via an Endpoint Reference
(EPR), as defined in WS-Addressing, and is able to be represented in XML format.
<bank:Account>
<bank:AccID>a1234567</bank:AccID>
<bank:First>Todd</bank:First>
<bank:Last>Meadows</bank:Last>
<bank:SSN>123456789</bank:SSN>
<bank:Balance>10000</bank:Balance>
</bank:Account>
… and an EPR to access it
<wsa:EndPointReference>
<wsa:Address>http://x.woodgrovebank.com/account</wsa:Address>
<wsa:ReferenceParameters>
<bank:AccID>a1234567</bank:AccID>
</wsa:ReferenceParameters>
</wsa:EndPointReference >
Getting Todd’s bank account resource
Firstly Todd wants to see how much money he has in his bank account (WS-Transfer).
Todd uses Transfer Get to retrieve his bank account details:
<soap:Envelope>
<soap:Header>
<wsa:To>http://x.woodgrovebank.com/account</wsa:To>
<bank:AccID wsa:IsReferenceParameter=“true”>a1234567</bank:AccID>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/transfer/Get
</wsa:Action>
</soap:Header>
<soap:Body />
</soap:Envelope>
The Response
<soap:Envelope>
<soap:Header>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse
</wsa:Action>
<bank:AccID wsa:IsReferenceParameter=“true”>a1234567</bank:AccID>
</soap:Header>
<soap:Body>
<bank:Account>
<bank:AccID>a1234567</bank:AccID>
<bank:First>Todd</bank:First>
<bank:Last>Meadows</bank:Last>
<bank:SSN>123456789</bank:SSN>
<bank:Balance>10000</bank:Balance>
</bank:Account>
</soap:Body>
</soap:Envelope>
Finding out about Transaction History Web
Service
When Todd sees his balance, he doesn’t think he has the right amount of money
available, and so wants to get his transaction history to find out what is going on.
Unfortunately he does not exactly know how to execute this operation and must
first understand what is required in order to successfully see this information
(WS-MetadataExchange).
Todd uses an EPR to retrieve the metadata about the TransactionHistory Web Service
<soap:Envelope>
<soap:Header>
<wsa:To>http://x.woodgrovebank.com/TransactionHistory/mex</wsa:To>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/transfer/Get
</wsa:Action>
</soap:Header>
<soap:Body />
</soap:Envelope>
The Response
<soap:Envelope>
<soap:Header>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse
</wsa:Action>
</soap:Header>
<soap:Body>
<mex:Metadata>
… metadata information here
</mex:Metadata>
</soap:Body>
</soap:Envelope>
The Metadata
<mex:Metadata>
<mex:MetadataSection Dialect='http://schemas.xmlsoap.org/wsdl/'>
<wsdl:definitions … >
…
</wsdl:definitions>
</mex:MetadataSection>
<mex:MetadataSection Dialect='http://www.w3.org/2001/XMLSchema'>
…
</mex:MetadataSection>
<mex:MetadataSection Dialect='http://schemas.xmlsoap.org/ws/2004/09/policy'>
<mex:MetadataReference>
<wsa:Address>http://x.woodgrovebank.com/TransactionHistory/policy</wsa:Address>
</mex:MetadataReference>
</mex:MetadataSection>
</mex:Metadata
Todd gets back too much information
Todd now realizes that the number of records is far too long to be retrieved at
once, and so he wants to break this down into a number of more manageable
pieces of information (WS-Enumeration).
…
<bank:Transactions>
<bank:Transaction id=”t14324”> info </bank:Transaction>
<bank:Transaction id=”t14325”> info </bank:Transaction>
<bank:Transaction id=”t14326”> info </bank:Transaction>
…
</bank:Transactions>
…
Enumeration: Basic Flow
1.
2.
3.
4.
5.
Send an Enumerate message to TransactionHistory
asking to enumerate it.
An opaque Enumeration Context (implementation
specific XML data) is returned.
Enumerate over the transaction data using a Pull
message.
Each Pull message will result in a set of transaction
items being returned.
Continue 3 and 4 until no more data is available or until
Todd finds what he is looking for.
Starting an Enumeration
<soap:Envelope>
<soap:Header>
<wsa:To>http://x.woodgrovebank.com/TransactionHistory</wsa:To>
<bank:AccID wsa:IsReferenceParameter=“true”>a1234567</bank:AccID>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/enumeration/Enumerate
</wsa:Action>
</soap:Header>
<soap:Body>
<wsen:Enumerate>
</wsen:Enumerate>
</soap:Body>
</soap:Envelope>
The Response
<soap:Envelope>
<soap:Header>
<bank:AccID wsa:IsReferenceParameter=“true”>a1234567</bank:AccID>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/enumeration/EnumerateResponse
</wsa:Action>
</soap:Header>
<soap:Body>
<wsen:EnumerateResponse>
<wsen:EnumerationContext>E#12345</wsen:EnumerationContext>
</wsen:EnumerateResponse>
</soap:Body>
</soap:Envelope>
Retrieving items in pieces
Todd can determine how many items to return using:
MaxTime, MaxElements, MaxCharacters
<soap:Envelope>
<soap:Header>
<wsa:To>http://x.woodgrovebank.com/TransactionHistory</wsa:To>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/enumeration/Pull
</wsa:Action>
</soap:Header>
<soap:Body>
<wsen:Pull>
<wsen:EnumerationContext>E#12345</wsen:EnumerationContext>
…
</wsen:Pull>
</soap:Body>
</soap:Envelope>
The Response
<soap:Envelope>
<soap:Header>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/enumeration/PullResponse
</wsa:Action>
</soap:Header>
<soap:Body>
<wsen:PullResponse>
<wsen:Items>
<bank:Transaction id=”t14324”> info </bank:Transaction>
<bank:Transaction id=”t14325”> info </bank:Transaction>
<bank:Transaction id=”t14326”> info </bank:Transaction>
…
</wsen:Items>
<wsen:EndOfSequence />
</wsen:PullResponse>
</soap:Body>
Todd wants to be informed
Finally Todd, after searching through his newly-chunked account transactions, has
found out that some strange person has been accessing his account without
permission, and so now he wants to be notified whenever any information in his
account changes (WS-Eventing).
Todd has to subscribe to account change events and then be prepared to accept
account change notifications sent to him.
Event Source – handles Subscribe messages, generates events
Event Sink – accepts event notifications
Subscription Manager – Intermediary which handles Renew, Unsubscribe messages
(in simple cases Event Source = Subscription Manager)
Subscribing to events
<soap:Envelope>
<soap:Header>
<wsa:To>http://x.woodgrovebank.com/account</wsa:To>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe
</wsa:Action>
</soap:Header>
<soap:Body>
<wse:Subscribe>
<wse:Delivery>
<wse:NotifyTo>
<wsa:Address>http://todd.adatum.com/customer</wsa:Address>
</wse:NotifyTo>
</wse:Delivery>
</wse:Subscribe>
</soap:Body>
</soap:Envelope>
The Response
<soap:Envelope>
<soap:Header>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/08/eventing/SubscribeResponse
</wsa:Action>
</soap:Header>
<soap:Body>
<wse:SubscribeResponse>
<wse:SubscriptionManager>
<wsa:Address>http://x.woodgrovebank.com/account</wsa:Address>
<wsa:ReferenceParameters>
<wse:Identifier>uuid:22e8a584-0d18-4228-b2a8</wse:Identifier>
</wsa:ReferenceParameters>
</wse:SubscriptionManager>
<wse:Expires>2010-07-01T00:00:00.000-00:00</wse:Expires>
</wse:SubscribeResponse>
</soap:Body>
</soap:Envelope>
The Subscription Manager
<soap:Envelope>
<soap:Header>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/08/eventing/SubscribeResponse
</wsa:Action>
</soap:Header>
<soap:Body>
<wse:SubscribeResponse>
<wse:SubscriptionManager>
<wsa:Address>http://x.woodgrovebank.com/account_manager</wsa:Address>
<wsa:ReferenceParameters>
<wse:Identifier>uuid:22e8a584-0d18-4228-b2a8</wse:Identifier>
</wsa:ReferenceParameters>
</wse:SubscriptionManager>
<wse:Expires>2010-07-01T00:00:00.000-00:00</wse:Expires>
</wse:SubscribeResponse>
</soap:Body>
</soap:Envelope>
Receiving events
http://todd.adatum.com/customer will start receiving account change messages…
<soap:Envelope>
<soap:Header>
<wsa:Action>
http://x.woodgrovebank.com/notifications/AccountChange
</wsa:Action>
</soap:Header>
<soap:Body>
<bank:AccountChange>
…
</bank:AccountChange>
</soap:Body>
</soap:Envelope>
Filtering Events
Todd quickly sees that he will be overrun with event notifications, as he starts to
receive thousands of events which represent the account changes occurring on
everyone’s bank accounts (clearly this would never happen in real life).
Todd uses Unsubscribe and then Subscribe, this time using a filter.
Filters can also be used in WS-Enumeration.
<soap:Body>
<wse:Subscribe>
<wse:Delivery>
…
</wse:Delivery>
<wse:Filter Dialect="http://x.woodgrovebank.com/accountFilter">
a1234567
</wse:Filter>
<wse:/Subscribe>
</soap:Body>
Knowing when Subscriptions Finish
<soap:Envelope>
<soap:Header>
<wsa:To>http://x.woodgrovebank.com/account</wsa:To>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe
</wsa:Action>
</soap:Header>
<soap:Body>
<wse:Subscribe>
<wse:Delivery>
<wse:NotifyTo>
<wsa:Address>http://todd.adatum.com/customer</wsa:Address>
</wse:NotifyTo>
</wse:Delivery>
<wse:EndTo>
<wsa:Address>http://todd.adatum.com/customer</wsa:Address>
</wse:EndTo>
</wse:Subscribe>
</soap:Body>
</soap:Envelope>
Subscription End Notification
<soap:Envelope …>
<soap:Header …>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/08/eventing/SubscriptionEnd
</wsa:Action>
</soap:Header>
<soap:Body>
<wse:SubscriptionEnd>
<wse:SubscriptionManager>
<wsa:Address>http://x.woodgrovebank.com/account_manager</wsa:Address>
</wse:SubscriptionManager>
<wse:Status>
http://schemas.xmlsoap.org/ws/2004/08/eventing/SourceShuttingDown
</wse:Status>
<wse:Reason>System reboot required</wse:Reason>
</wse:SubscriptionEnd>
</soap:Body>
</soap:Envelope>
Subscription Identification

A Subscribe message is sent to the event source that contains:



The event source responds with a Subscribe Response
message that may contain:


Event Source-defined wse:Identifier C in the subscription manager
EPR in the body
The Event source will send event notification messages that
contain:


A user-defined reference parameter A in the NotifyTo EPR in the
body
A user-defined reference parameter B in the EndTo EPR in the body
User-defined reference parameter A in the header
The Event source will send a Subscription End message that
contains:


User-defined reference parameter B in the header
Event Source-defined wse:Identifier C in the body
References

Web Services Metadata Exchange (WS-MetadataExchange)


Web Services Transfer (WS-Transfer)


http://www.w3.org/2005/08/addressing
Web Services Description Language (WSDL)


http://www.w3.org/TR/2007/REC-soap12-part1-20070427/
Web Services Addressing (WS-Addressing)


http://www.w3.org/Submission/WSRT/
Simple Object Access Protocol (SOAP) 1.2


http://www.w3.org/Submission/WS-Enumeration/
Web Services Resource Transfer (WS-RT)


http://www.w3.org/Submission/WS-Eventing/
Web Services Enumeration (WS-Enumeration)


http://www.w3.org/Submission/WS-Transfer/
Web Services Eventing (WS-Eventing)


http://www.w3.org/Submission/WS-MetadataExchange/
http://www.w3.org/TR/2001/NOTE-wsdl-20010315
XML Path Language Version 1.0

http://www.w3.org/TR/1999/REC-xpath-19991116