Understanding Web Service Resource Access

Geoff BullenMicrosoft

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

A general SOAP-based protocol for creating, retrieving, updating and deleting XML representations of Web service-based resources.

WS-MetadataExchange A general purpose metadata encapsulation format and a

protocol for retrieving Web service metadata. WS-Enumeration

Enumerating a sequence of XML elements. WS-Eventing

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

5

Assurances

Messaging

SOAP

WS-Security

MTOM

Metadata

WSDLWS-Transfer WS-Eventing

XML Schema

Infrastructureand Profiles

Foundation

SOAP / HTTPMIME

XML Infoset

XML 1.0 XMLNamespaces

WS-Addressing

WS-Policy

WS-MetadataExchange

SOAP / UDP

WS-Enumeration

WS-Trust

WS-SecureConversation

WS-FederationWS-ManagementDevices Profile

UDDI

WS-Discovery

WS-ReliableMessaging WS-Coordination

WS-AtomicTransaction

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.

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.

Firstly Todd wants to see how much money he has in his bank account (WS-Transfer).

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 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

<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>

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.

… 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

<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>

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:

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

<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>

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

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

… <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>…

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).

Enumeration: Basic Flow1. Send an Enumerate message to

TransactionHistory asking to enumerate it.2. An opaque Enumeration Context

(implementation specific XML data) is returned.

3. Enumerate over the transaction data using a Pull message.

4. Each Pull message will result in a set of transaction items being returned.

5. 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

<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>

Todd can determine how many items to return using:MaxTime, MaxElements, MaxCharacters

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 informedFinally 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 eventsEvent Sink – accepts event notificationsSubscription 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

<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>

http://todd.adatum.com/customer will start receiving account change messages…

Filtering Events

<soap:Body> <wse:Subscribe> <wse:Delivery> … </wse:Delivery> <wse:Filter Dialect="http://x.woodgrovebank.com/accountFilter"> a1234567 </wse:Filter> <wse:/Subscribe></soap:Body>

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.

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:

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

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: 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)

http://www.w3.org/Submission/WS-MetadataExchange/ Web Services Transfer (WS-Transfer)

http://www.w3.org/Submission/WS-Transfer/ Web Services Eventing (WS-Eventing)

http://www.w3.org/Submission/WS-Eventing/ Web Services Enumeration (WS-Enumeration)

http://www.w3.org/Submission/WS-Enumeration/ Web Services Resource Transfer (WS-RT)

http://www.w3.org/Submission/WSRT/ Simple Object Access Protocol (SOAP) 1.2

http://www.w3.org/TR/2007/REC-soap12-part1-20070427/ Web Services Addressing (WS-Addressing)

http://www.w3.org/2005/08/addressing Web Services Description Language (WSDL)

http://www.w3.org/TR/2001/NOTE-wsdl-20010315 XML Path Language Version 1.0

http://www.w3.org/TR/1999/REC-xpath-19991116