Understanding Web Service Resource Access Geoff Bullen Microsoft

Overview � Introduction to Resource Access Web Services � The Banking Scenario � Transfer � Metadata. Exchange � 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 servicebased resources. � WS-Metadata. Exchange � 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-Resource. Transfer � Extensions to WS-Transfer to define fragment-based operations.

Web Services Specifications WS-Federation WS-Management Infrastructure Devices Profile and Profiles 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 Metadata SOAP / HTTP 5 Foundation

SOAP Message – Request <soap: Envelope> <soap: Header> <wsa: To>http: //x. woodgrovebank. com/Transaction. History</wsa: To> <wsa: Reply. To> <wsa: Address>http: //todd. adatum. com/customer</wsa: Address> </wsa: Reply. To> <wsa: Action>http: //x. woodgrovebank. com/Get. History</wsa: Action> <bank: Acc. ID wsa: Is. Reference. Parameter=“true”>a 1234567</bank: Acc. ID> … </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/History. Response</wsa: Action> <bank: Acc. ID wsa: Is. Reference. Parameter=“true”>a 1234567</bank: Acc. ID> … </soap: Header> <soap: Body> <bank: Transactions> <bank: Transaction id=”t 14324”> info </bank: Transaction> <bank: Transaction id=”t 14325”> info </bank: Transaction> <bank: Transaction id=”t 14326”> 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 (WSMetadata. Exchange). 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: Acc. ID>a 1234567</bank: Acc. ID> <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: End. Point. Reference> <wsa: Address>http: //x. woodgrovebank. com/account</wsa: Address> <wsa: Reference. Parameters> <bank: Acc. ID>a 1234567</bank: Acc. ID> </wsa: Reference. Parameters> </wsa: End. Point. Reference >

Getting Todd’s bank account resource Firstly Todd wants to see how much money he has in his bank account (WS-Transfe Todd uses Transfer Get to retrieve his bank account details: <soap: Envelope> <soap: Header> <wsa: To>http: //x. woodgrovebank. com/account</wsa: To> <bank: Acc. ID wsa: Is. Reference. Parameter=“true”>a 1234567</bank: Acc. ID> <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/Get. Response </wsa: Action> <bank: Acc. ID wsa: Is. Reference. Parameter=“true”>a 1234567</bank: Acc. ID> </soap: Header> <soap: Body> <bank: Account> <bank: Acc. ID>a 1234567</bank: Acc. ID> <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-Metadata. Exchange). Todd uses an EPR to retrieve the metadata about the Transaction. History Web <soap: Envelope> Service <soap: Header> <wsa: To>http: //x. woodgrovebank. com/Transaction. History/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/Get. Response </wsa: Action> </soap: Header> <soap: Body> <mex: Metadata> … metadata information here </mex: Metadata> </soap: Body> </soap: Envelope>

The Metadata <mex: Metadata> <mex: Metadata. Section Dialect='http: //schemas. xmlsoap. org/wsdl/'> <wsdl: definitions … > … </wsdl: definitions> </mex: Metadata. Section> <mex: Metadata. Section Dialect='http: //www. w 3. org/2001/XMLSchema'> … </mex: Metadata. Section> <mex: Metadata. Section Dialect='http: //schemas. xmlsoap. org/ws/2004/09/policy'> <mex: Metadata. Reference> <wsa: Address>http: //x. woodgrovebank. com/Transaction. History/policy</wsa: Addres </mex: Metadata. Reference> </mex: Metadata. Section> </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=”t 14324”> info </bank: Transaction> <bank: Transaction id=”t 14325”> info </bank: Transaction> <bank: Transaction id=”t 14326”> info </bank: Transaction> … </bank: Transactions> …

Enumeration: Basic Flow 1. 2. 3. 4. 5. Send an Enumerate message to Transaction. History 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/Transaction. History</wsa: To> <bank: Acc. ID wsa: Is. Reference. Parameter=“true”>a 1234567</bank: Acc. ID> <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/09/enumeration/Enumerate </wsa: Action> </soap: Header> <soap: Body> <wsen: Enumerate> </soap: Body> </soap: Envelope>

The Response <soap: Envelope> <soap: Header> <bank: Acc. ID wsa: Is. Reference. Parameter=“true”>a 1234567</bank: Acc. ID> <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/09/enumeration/Enumerate. Response </wsa: Action> </soap: Header> <soap: Body> <wsen: Enumerate. Response> <wsen: Enumeration. Context>E#12345</wsen: Enumeration. Context> </wsen: Enumerate. Response> </soap: Body> </soap: Envelope>

Retrieving items in pieces Todd can determine how many items to return using: Max. Time, Max. Elements, Max. Characters <soap: Envelope> <soap: Header> <wsa: To>http: //x. woodgrovebank. com/Transaction. History</wsa: To> <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/09/enumeration/Pull </wsa: Action> </soap: Header> <soap: Body> <wsen: Pull> <wsen: Enumeration. Context>E#12345</wsen: Enumeration. Context> … </wsen: Pull> </soap: Body> </soap: Envelope>

The Response <soap: Envelope> <soap: Header> <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/09/enumeration/Pull. Response </wsa: Action> </soap: Header> <soap: Body> <wsen: Pull. Response> <wsen: Items> <bank: Transaction id=”t 14324”> info </bank: Transaction> <bank: Transaction id=”t 14325”> info </bank: Transaction> <bank: Transaction id=”t 14326”> info </bank: Transaction> … </wsen: Items> <wsen: End. Of. Sequence /> </wsen: Pull. Response> </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: Notify. To> <wsa: Address>http: //todd. adatum. com/customer</wsa: Address> </wse: Notify. To> </wse: Delivery> </wse: Subscribe> </soap: Body> </soap: Envelope>

The Response <soap: Envelope> <soap: Header> <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/08/eventing/Subscribe. Response </wsa: Action> </soap: Header> <soap: Body> <wse: Subscribe. Response> <wse: Subscription. Manager> <wsa: Address>http: //x. woodgrovebank. com/account</wsa: Address> <wsa: Reference. Parameters> <wse: Identifier>uuid: 22 e 8 a 584 -0 d 18 -4228 -b 2 a 8</wse: Identifier> </wsa: Reference. Parameters> </wse: Subscription. Manager> <wse: Expires>2010 -07 -01 T 00: 00. 000 -00: 00</wse: Expires> </wse: Subscribe. Response> </soap: Body> </soap: Envelope>

The Subscription Manager <soap: Envelope> <soap: Header> <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/08/eventing/Subscribe. Response </wsa: Action> </soap: Header> <soap: Body> <wse: Subscribe. Response> <wse: Subscription. Manager> <wsa: Address>http: //x. woodgrovebank. com/account_manager</wsa: Address <wsa: Reference. Parameters> <wse: Identifier>uuid: 22 e 8 a 584 -0 d 18 -4228 -b 2 a 8</wse: Identifier> </wsa: Reference. Parameters> </wse: Subscription. Manager> <wse: Expires>2010 -07 -01 T 00: 00. 000 -00: 00</wse: Expires> </wse: Subscribe. Response> </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/Account. Change </wsa: Action> </soap: Header> <soap: Body> <bank: Account. Change> … </bank: Account. Change> </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/account. Filter"> a 1234567 </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: Notify. To> <wsa: Address>http: //todd. adatum. com/customer</wsa: Address> </wse: Notify. To> </wse: Delivery> <wse: End. To> <wsa: Address>http: //todd. adatum. com/customer</wsa: Address> </wse: End. To> </wse: Subscribe> </soap: Body> </soap: Envelope>

Subscription End Notification <soap: Envelope …> <soap: Header …> <wsa: Action> http: //schemas. xmlsoap. org/ws/2004/08/eventing/Subscription. End </wsa: Action> </soap: Header> <soap: Body> <wse: Subscription. End> <wse: Subscription. Manager> <wsa: Address>http: //x. woodgrovebank. com/account_manager</wsa: Address> </wse: Subscription. Manager> <wse: Status> http: //schemas. xmlsoap. org/ws/2004/08/eventing/Source. Shutting. Down </wse: Status> <wse: Reason>System reboot required</wse: Reason> </wse: Subscription. End> </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 Notify. To EPR in the body � A user-defined reference parameter B in the End. To 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-Metadata. Exchange) � � Web Services Transfer (WS-Transfer) � � http: //www. w 3. org/2005/08/addressing Web Services Description Language (WSDL) � � http: //www. w 3. org/TR/2007/REC-soap 12 -part 1 -20070427/ Web Services Addressing (WS-Addressing) � � http: //www. w 3. org/Submission/WSRT/ Simple Object Access Protocol (SOAP) 1. 2 � � http: //www. w 3. org/Submission/WS-Enumeration/ Web Services Resource Transfer (WS-RT) � � http: //www. w 3. org/Submission/WS-Eventing/ Web Services Enumeration (WS-Enumeration) � � http: //www. w 3. org/Submission/WS-Transfer/ Web Services Eventing (WS-Eventing) � � http: //www. w 3. org/Submission/WS-Metadata. Exchange/ http: //www. w 3. org/TR/2001/NOTE-wsdl-20010315 XML Path Language Version 1. 0 � http: //www. w 3. org/TR/1999/REC-xpath-19991116